Verification Protocol

STOP. You are NOT done yet. Generate this checklist and provide EVIDENCE for every item.

---

1. Task Type & Strategy

• Type: FIX / FEATURE / REFACTOR / DOCS / INVESTIGATION
• Strategy: Executable verification vs. Static verification?

---

[!IMPORTANT] When provided a process map or Mermaid diagram, treat it as the authoritative procedure. Execute steps in the exact order shown, including branches, decision points, and stop conditions. A Mermaid process diagram is an executable instruction set. Follow it exactly as written: respect sequence, conditions, loops, parallel paths, and terminal states. Do not improvise, reorder, or skip steps. If any node is ambiguous or missing required detail, pause and ask a clarifying question before continuing. When interacting with a user, report before acting the interpreted path you will follow from the diagram, then execute.

2. The "WORKS" Check

<!-- Converted from prose branch instruction: "Choose A or B based on task type" -->

The following diagram is the authoritative procedure for WORKS Check — determining whether the task output is verified as working. Execute steps in the exact order shown, including branches, decision points, and stop conditions.

flowchart TD
    Start(["Begin WORKS Check -- Section 2"]) --> Q{"Task type?"}
    Q -->|"Executable code -- compiled, scripted, or CLI-run"| A1["Execution check<br>Terminal output showing successful run<br>(exit code 0 is NOT enough)"]
    Q -->|"Static asset -- docs, configs, analysis"| B1["Accuracy check<br>Verified against source code or schema?"]
    A1 --> A2["Real data check<br>Ran changed code path against real data<br>not just read the diff?"]
    A2 --> A3["Regression check<br>Evidence that existing tests still pass?"]
    A3 --> A4["Edge case check<br>Evidence of testing failure scenarios?"]
    A4 --> AEvidence["Record code evidence<br>execution output, real data test,<br>test results, edge case result"]
    B1 --> B2["Clarity check<br>Follows the established format?"]
    B2 --> B3["Validity check<br>Links and references resolve?"]
    B3 --> BEvidence["Record static evidence<br>accuracy check method,<br>format standard, link validation method"]
    AEvidence --> Done(["WORKS Check complete -- proceed to Section 3"])
    BEvidence --> Done

A. For Code (Executable)

• Execution: Terminal output showing successful run? (Exit code 0 is NOT enough)
• Real data: Ran the changed code path against real data, not just read the diff?
• Regression: Evidence that existing tests still pass?
• Edge Cases: Evidence of testing failure scenarios?

EVIDENCE:
- Execution output: [paste actual output]
- Real data test: [command run, input used, output observed]
- Test results: [paste test output]
- Edge case tested: [describe scenario and result]

B. For Static Assets (Docs, Configs, Analysis)

• Accuracy: Verified against source code/schema?
• Clarity: Does it follow the established format?
• Validity: Do links/references resolve?

EVIDENCE:
- Accuracy check: [how verified]
- Format compliance: [standard followed]
- Links validated: [method used]

---

3. The "FIXED" Check

For bug fixes specifically:

• Reproduction: Did I observe the pre-fix state?
• Resolution: Does the original problem NO LONGER occur?

EVIDENCE:
- Pre-fix behavior: [what was observed]
- Post-fix behavior: [what is now observed]
- Regression test added: [yes/no, location]

---

4. Quality Gates

• Pre-commit hooks passed?
• Linting passed?
• Type checking passed? (if applicable)

EVIDENCE:
- Pre-commit: [output or "not configured"]
- Linting: [tool and result]
- Type check: [tool and result]

---

5. Proportional Response Check

If the task has an issue-classification field in its metadata, verify the response matched the issue type. If no issue-classification is present, mark N/A and proceed.

The following diagram is the authoritative procedure for Proportional Response Check — verifying that the response scope matched the issue classification. Execute steps in the exact order shown, including branches, decision points, and stop conditions.

flowchart TD
    Start(["Begin Proportional Response Check"]) --> Q1{"issue-classification<br>present in task metadata?"}
    Q1 -->|"absent"| Skip["SKIP -- existing WORKS/FIXED/Quality Gates apply"]
    Q1 -->|"present"| Q2{"Classification type?"}
    Q2 -->|"procedural"| P["Sweep completeness<br>Codebase search returns zero<br>remaining instances of the pattern"]
    Q2 -->|"defect"| D["Root cause addressed<br>Fix targets root cause from evidence chain<br>+ scenario in scenario-target succeeds"]
    Q2 -->|"recurring-pattern"| R["Guardrail added<br>New gate/check exists AND<br>covers the defect CLASS not just instance"]
    Q2 -->|"missing-guardrail"| M["Gate gap filled<br>Guardrail triggers in the<br>exposing scenario"]
    Q2 -->|"unbounded-design"| U["Design implemented<br>Matches chosen direction +<br>trade-offs documented"]
    P --> Evidence
    D --> Evidence
    R --> Evidence
    M --> Evidence
    U --> Evidence
    Skip --> Done(["Proportional Check complete"])
    Evidence["Record proportional evidence"] --> Done

EVIDENCE:
- Issue Classification: [type or "not classified"]
- Scenario Target: [scenario -> improvement, or "not specified"]
- Proportional Check: [PASS/FAIL/N/A]
- Check detail: [what was verified and result]

---

6. Agent Delegation Verification

When work was delegated to a sub-agent, the agent's success report is NOT evidence.

• VCS diff reviewed: git diff shows the expected changes?
• Changes verified: Read the modified files — content matches intent?
• Tests run independently: Ran the verification command yourself, not trusting the agent's claim?

EVIDENCE:
- Agent report: [what agent claimed]
- VCS diff: [files changed, scope matches expectation]
- Independent verification: [command run, output observed]

If no agents were used, mark N/A and proceed.

---

7. Honesty Check

• Did I verify the full scope?
• Am I distinguishing between "should work" and "verified to work"?
• Destination check: Did I read the target state after writing? (Tool output claiming success is not evidence — the state of the destination is.)
• Can I answer YES to: "I have VALIDATED this output in its intended context"?

Rationalization Prevention

If any of these thoughts occur, STOP and run the verification command:

Rationalization	Response
"Should work now"	Run the verification command
"I'm confident"	Confidence is not evidence
"Just this once"	No exceptions
"Linter passed so build passes"	Linter does not check compilation
"Agent said success"	Verify independently (Section 6)
"I'm tired"	Exhaustion is not an excuse
"Partial check is enough"	Partial check proves nothing about the whole
"Different words so rule doesn't apply"	Spirit over letter

Red flags in your own output — if you catch yourself writing any of these, the gate has not been passed:

• "should", "seems to", "looks correct"
• Expressions of satisfaction before verification ("Done!", "Perfect!")
• About to commit/push/PR without fresh command output in this message

---

The Golden Rule

If you cannot demonstrate it working in practice with evidence, it is NOT done.

Claim	Required Evidence
"Code works"	Terminal output showing execution against real data
"Tests pass"	Actual test output, not assumption
"Bug fixed"	Before/after comparison
"Data synced"	Read the destination after writing — not the tool output
"Docs accurate"	Cross-reference with source
"Config valid"	Validation command output
"Root cause fixed"	Evidence chain from grooming + fix addresses root cause claim
"Guardrail added"	New gate/check exists and triggers in exposing scenario
"Agent completed"	VCS diff reviewed + independent verification command run

---

8. Observations, Gaps, and Backlog Capture

Review the task just completed and list every instance of:

• Workflow gaps — steps that were missing, unclear, or required guessing to proceed
• Workarounds — anything done as a workaround rather than the correct approach
• Process concerns — agent behaviors or system interactions that indicate a systemic problem
• Improvement observations — things noticed that could be better if addressed, even if not blocking

The following diagram is the authoritative procedure for Observations, Gaps, and Backlog Capture — triaging observations from the completed task into backlog items or recorded notes. Execute steps in the exact order shown, including branches, decision points, and stop conditions.

flowchart TD
    List["List all instances across the categories above"] --> Q{"Any items listed?"}
    Q -->|"None"| None["Record: No observations"]
    Q -->|"Yes"| Gate{"Any item is contextually significant<br>OR was already flagged during the task<br>as needing a bug or backlog entry?"}
    Gate -->|"No — minor, not worth a ticket"| ObsOnly["Record as observation only<br>Include in summary below"]
    Gate -->|"Yes — significant"| Detect{"Is the dh plugin installed in this project?"}
    Detect -->|"No"| Other["Create entry in whatever issue system the project uses"]
    Detect -->|"Yes"| Resolve{"Which backend does it resolve to?<br>Follow the dh:backend-resolution skill"}
    Resolve -->|"beads"| Beads["bd create --title='...' --description='...' --type=bug --priority=2<br>Canonical Beads-native follow-up"]
    Resolve -->|"any other backend"| DH["Skill(skill='dh:work-backlog-item', args='create -- \"...\"')"]
    Beads --> Ref["Record issue reference in summary"]
    DH --> Ref
    Other --> Ref
    Ref --> Done(["Observations Check complete"])
    None --> Done
    ObsOnly --> Done

OBSERVATIONS:
- Workflow gaps:    [list or "none"]
- Workarounds:      [list or "none"]
- Process concerns: [list or "none"]
- Improvements:     [list or "none"]
- Issues logged:    [issue refs or "none"]

The first fork asks whether this project has a dh backend at all. Many do not — this checklist runs anywhere. When there is none, the Other branch stands on its own: file the follow-up wherever that project tracks issues, and nothing below applies.

When there is one, use the /dh:backend-resolution skill to determine which backend it is. Do not infer it from what is on disk: testing for the .beads/dh-backend marker on its own inverts the resolution order, so a project that carries the marker but configures a different backend resolves to that other backend, and filing the follow-up with bd would put it somewhere the project's own tooling does not read.

For a Beads workspace, the bd create branch above is canonical for native follow-ups; do not route the same CRUD operation through sam backlog merely for symmetry. Use DH CLI/MCP only for structured plans, dispatch, artifacts, validation, or capabilities Beads does not provide.

---

Quick Reference

VERIFICATION SUMMARY:
Task Type: [FIX/FEATURE/REFACTOR/DOCS/INVESTIGATION]
Works Check: [PASS/FAIL] - Evidence: ___
Fixed Check: [PASS/FAIL/N/A] - Evidence: ___
Proportional Check: [PASS/FAIL/N/A] - Evidence: ___
Quality Gates: [PASS/FAIL] - Evidence: ___
Agent Delegation: [PASS/FAIL/N/A] - Evidence: ___
Honesty Check: [PASS/FAIL]
Observations: [issue refs logged, or "none"]

VERDICT: [COMPLETE / NOT COMPLETE - reason]