mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-07-21 18:33:22 -07:00
v1.14.0 — add Step 3b review workflow, unify file naming, resilient code references
- Add /plan2code-3b-review: 5-step post-implementation review with adaptive scope, 11 dimensions, reference-file architecture, and Plan/Apply/Verify fixes - Unify workflow/skill file naming to single-dash (drop -- and --- conventions) - Add Devin platform support and CLAUDE.md MANDATORY FIRST STEP template - Guide agents to use semantic anchors over line numbers in workflow prompts - Bump version to 1.14.0
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# Verification Protocol
|
||||
> Part of plan2code-3b-review — loaded during Step 3 (Analyze).
|
||||
|
||||
Apply this protocol to every finding before presenting it. Findings that fail verification are dropped. No exceptions.
|
||||
|
||||
## Code Finding Verification
|
||||
|
||||
1. **Re-read the source.** Open the file and read the actual line(s) cited. Do not rely on memory or earlier reads.
|
||||
2. **Read surrounding context.** At least 20 lines above and below. Many "bugs" are handled by guards, defaults, or patterns in surrounding code.
|
||||
3. **Verify the issue is real.** Trace the variable/function's actual usage. Is the edge case reachable? Does a try/catch or guard upstream already handle this?
|
||||
4. **Verify the fix doesn't break callers.** Search all call sites. Check if any caller depends on the current behavior. Verify the fix maintains the function's contract.
|
||||
5. **Check the test suite.** Do tests cover this case (making the "bug" intentional)? Would your fix break existing tests?
|
||||
|
||||
## Architectural Finding Verification
|
||||
|
||||
Architectural findings carry the highest false-positive risk.
|
||||
|
||||
1. **Identify all consumers.** Search the entire codebase — imports, requires, config files, build scripts, documentation, dynamic references (string-based requires, Read directives).
|
||||
2. **Trace a concrete use case end-to-end.** Start at the entry point, follow execution through every module, document where the component you want to change is touched. If you can't trace a complete use case, you don't understand the system well enough to recommend changes.
|
||||
3. **Simulate the change.** Walk the same use case with your change applied. At each step: can it still complete successfully? Pay attention to steps that load data, read config, or reference files.
|
||||
4. **Check indirect dependencies.** Reference data loaded by agents at runtime via Read directives. Config consumed by external tools or CI/CD. Exports consumed by other packages.
|
||||
5. **Verify the motivation.** Am I improving correctness, or satisfying an aesthetic preference? Is the complexity I'm flagging intentional?
|
||||
|
||||
## Design Finding Verification
|
||||
|
||||
1. **Check project conventions.** Read AGENTS.md, README, existing patterns. Is the "inconsistency" a deliberate choice?
|
||||
2. **Simulate across all consumers.** Does the change improve their code, or just move complexity? Would it require coordinated updates across files?
|
||||
3. **Evaluate migration cost.** Is the current design causing actual bugs, or merely suboptimal?
|
||||
4. **Check platform constraints.** Does the recommendation work across all supported platforms?
|
||||
|
||||
## Confidence Calibration
|
||||
|
||||
| Level | Definition | Action |
|
||||
|-------|-----------|--------|
|
||||
| **High** | Verified in source code AND use-case traced (for arch/design). Issue confirmed real, fix confirmed safe. | Present. |
|
||||
| **Not High** | Any doubt remains. | Investigate further or drop entirely. |
|
||||
|
||||
No Medium or Low tier. A finding is verified or it isn't.
|
||||
|
||||
## Adversarial Self-Check
|
||||
|
||||
Run against EVERY finding. If any question raises doubt, re-investigate or drop.
|
||||
|
||||
1. **Am I optimizing for the wrong metric?** Reducing file count, context size, or complexity when the structure serves correctness or platform compatibility?
|
||||
2. **Does my fix remove something the system depends on?** Verified by searching ALL consumers, not just the current file?
|
||||
3. **Have I traced a real use case end-to-end with my fix applied?**
|
||||
4. **Am I recommending removal because I don't understand the purpose?**
|
||||
5. **Would a domain expert disagree with this finding?**
|
||||
|
||||
## Escalation Rules
|
||||
|
||||
- **One question uncertain:** Re-investigate. If doubt persists, drop.
|
||||
- **Two+ questions uncertain:** Drop entirely.
|
||||
- **Cannot investigate:** Drop entirely. Note the gap in Step 4 if the dimension matters.
|
||||
|
||||
## Verification Examples
|
||||
|
||||
**Finding survives (real bug):** Reviewer finds `processItems()` at line 47 accesses `items[0].id` with no empty-array check. Re-reads source — confirmed no guard. Traces callers — `orchestrator.js:82` can pass empty array. Adversarial check passes (correctness issue, additive fix). Presented at High.
|
||||
|
||||
**Finding dropped (pcweb-jira false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
|
||||
|
||||
**Finding dropped (false consolidation):** Reviewer flags per-platform config files as "duplicates." Adversarial check: "Am I optimizing for the wrong metric?" YES — platforms have distinct values and will diverge further. Separation is a design choice. Dropped.
|
||||
|
||||
## Review Discipline (Reinforcement)
|
||||
|
||||
These rules are restated here for reinforcement at analysis time — they are critical and must not drift:
|
||||
|
||||
- **Every finding must reference actual code at file:line.** Never fabricate. If you can't cite it, don't report it.
|
||||
- **High confidence required.** No Low confidence findings. Investigate until verified or drop entirely.
|
||||
- **Read every changed file completely before flagging.** Context missed = false positive generated.
|
||||
- **Never silently narrow scope.** Review what was asked, not what's convenient.
|
||||
- **Verify docs match code.** Documentation that contradicts implementation is a finding.
|
||||
Reference in New Issue
Block a user