impl-verify

Impl-Verify — Implementation Correctness Verification

After implementation completes and before marking the task done, perform multi-dimensional cross-validation of code changes: code logic ↔ requirements / domain knowledge / Plan / engineering standards. Converge over multiple rounds; exit only with zero must-fix findings.

Announce at start: "Using ecw:impl-verify to verify implementation correctness."

Output language: Read ecw.yml → project.output_language.

Relationship with Other Verification Components

Component	What It Verifies	Execution Model	Mandatory?
ecw:impl-verify (this skill)	Code correctness + quality	Multi-round convergence, exit on zero must-fix	Yes (P0-P2)
verify-completion hook	Compilation, tests, reference integrity, knowledge sync	Auto-intercept	Yes (automatic)
ecw:biz-impact-analysis	Business impact scope	Single analysis	Yes (P0/P1 mandatory)
ecw:cross-review	Inter-file structural consistency	Multi-round convergence	No (manual, optional)
ecw:spec-challenge	Plan blind spots, boundary conditions	Challenge-response	Plan phase, not implementation phase

Input Material Collection

Before execution, locate input materials in the following order:

Material	Source	Round
Requirement document	Current session's requirements-elicitation output / domain-collab report / user's original requirement description	Round 1
Domain knowledge	.claude/knowledge/{domain}/business-rules.md, data-model.md (locate affected domains via path-mappings.md)	Round 2
Plan file	Plan file produced by writing-plans in current session	Round 3
Changed code	git diff --name-only + git diff (get file list and detailed changes)	All Rounds
Project patterns	Existing code's naming/layering/error-handling conventions	Round 4

Knowledge file read priority (Round 2):

1. First check if .claude/ecw/session-data/{workflow-id}/knowledge-summary.md exists and covers domains affected by this change
2. If summary file is sufficient (contains state machine, validation rules, data model sections), execute Round 2 based on summary
3. If summary does not exist or is insufficient, read full domain knowledge files

Knowledge file robustness (Round 2): Before reading any domain knowledge file, verify it exists. If business-rules.md or data-model.md for a domain is missing, log [Warning: {domain}/{file} not found, Round 2 checks for this domain degraded] in the Round 2 findings. The subagent should still check available files and report what dimensions could not be verified.

Degradation handling:

• No requirement document (P3 or degraded scenario) → Skip Round 1, warn user
• No domain knowledge files → Skip Round 2, warn user
• No Plan file → Skip Round 3, warn user
• None of the above available → Execute Round 4 only (engineering standards), output warning

Diff Read Strategy (Reduce Redundancy)

1. Coordinator pre-processing: Execute git diff --name-only once to get the changed file list. Pass this list (not full diff content) to all Round subagents
2. Round 1-4 subagents (parallel): Each subagent independently reads code changes for its verification needs. Use targeted git diff -- {specific file} for files relevant to that Round's dimension, rather than reading full git diff for all files. This keeps each subagent's context lean
3. Round N+ (fix re-verification): Only execute git diff HEAD~1 -- {file} for files involved in fixes to get incremental changes. Do not re-read the full baseline diff
4. Changed file table cache: The changed file list from coordinator pre-processing serves as the index for all Rounds; each subagent receives it as input

Subagent Dispatch Architecture

To prevent context overflow in the coordinator, each verification Round is dispatched as an independent subagent. The coordinator only holds the lightweight change summary and aggregated findings.

Coordinator responsibilities:

1. Execute git diff --name-only to get the changed file list (lightweight)
2. Dispatch Round 1-4 as parallel subagents (4 Agent tool calls in a single message)
3. Per-round immediate persistence: As soon as each Round subagent returns, immediately append its results (with round header) to .claude/ecw/session-data/{workflow-id}/impl-verify-findings.md. Do NOT wait for all rounds to complete before persisting — each round is appended independently. This ensures completed round results survive even if subsequent rounds fail or context is compacted mid-verification.
4. Deduplicate findings across Rounds
5. Finalize findings: Before creating any fix Tasks or presenting to user, ensure impl-verify-findings.md is complete and deduplicated. Format per finding: severity, Round, file:line, description, expected vs actual, fix suggestion. After each re-verification round, append new findings and mark fixed ones as [FIXED]. This ensures a complete view survives context compaction.
6. Present findings to user, handle convergence loop

Each Round subagent is dispatched with subagent_type: "ecw:impl-verifier", which auto-injects the agent's base instructions (verification approach, output format, reading limits). Coordinator passes round-specific reference material and verification checklist in the prompt parameter.

Each Round subagent receives:

• Changed file list (from coordinator)
• Round-specific reference material paths (not content — the subagent reads them)
• Verification checklist for that Round (Read ./prompts/round-checklists.md and pass the relevant Round section)
• Output format specification

Each Round subagent returns structured findings:

round: 1  # or 2, 3, 4
findings:
  - file: "path/to/file.java"
    line: 42
    severity: must-fix  # or suggestion
    dimension: "requirements-tracing"  # or domain-rules, plan-decisions, engineering-standards
    description: "Description of the finding"
    expected: "What was expected"
    actual: "What was found"
status: pass  # or has-findings
summary: "One-line summary of this round"

Parallel dispatch: Rounds 1-4 verify independent dimensions and do not depend on each other's results. They MUST be dispatched in parallel (multiple Agent tool calls in a single assistant message) for efficiency.

Return value validation: For each Round subagent, verify the YAML contains required fields (round, findings, status, summary). For each finding, verify file, severity, and description exist. If validation fails:

1. Log to Ledger: [FAILED: impl-verify Round {N}, reason: invalid return format]
2. Retry once with the same model
3. If retry also fails: mark that Round as [incomplete: Round {N}] in the output, continue with findings from other Rounds. Do not block convergence — but warn user that one verification dimension was skipped.

Model selection: Use model: "sonnet" (default from models.defaults.verification; configurable via ecw.yml) for all verification subagents. Reason: verification is pattern-matching against reference material — does not require Opus-level reasoning.

Timeout per Round subagent: 180s. If a Round subagent has not returned within this time, terminate it and fall back to coordinator inline execution for that Round (see Error Handling).

Execution Protocol

Coordinator dispatches Rounds 1-4 as parallel ecw:impl-verifier subagents. Each subagent receives the relevant section from ./prompts/round-checklists.md:

• Round 1 — Requirements ↔ Code: bidirectional tracing checklist
• Round 2 — Domain Knowledge ↔ Code: domain rule alignment checklist
• Round 3 — Plan ↔ Code: plan decision verification checklist
• Round 4 — Engineering Standards ↔ Code: engineering standards quality review checklist

Before generating output, each subagent reads ./output-templates.md for per-round findings format, zero-findings format, and final pass summary structure. For severity judgment rules, read ./prompts/common-rationalizations.md.

Round N+ (Conditional Trigger) — Fix Re-Verification

Triggered only when any previous Round has must-fix findings that have been fixed.

Operations:

1. Collect all files involved in fixes
2. Re-run related dimension checks on those files (not a full re-run — only the affected Rounds)
3. Append each re-verification round result to impl-verify-findings.md (with round header and dimension label), marking previously reported findings for that dimension as [FIXED] or [STILL-OPEN].
4. If this round still has must-fix findings, continue fixing and trigger next round
5. If user also addressed suggestion-level issues, re-verification covers those changes too (ensure no new issues introduced)

Incremental re-verification: When dispatching Round N+, only dispatch subagents for Rounds that had must-fix findings. Pass only the files involved in fixes (incremental diff), not the full change set. This reduces subagent context consumption during convergence.

Convergence Condition

Most recent round has zero must-fix findings → exit, output verification passed report.

• Suggestion-level findings do not block convergence; recorded in final report for reference
• Loop cap: Maximum 5 rounds. If must-fix findings remain after 5 rounds, output all unresolved items and suggest user intervention
• Stall detection: If must-fix count does not decrease for 2 consecutive rounds (Round N and N+1 have equal or higher must-fix count), stop iterating and escalate to user: [Stall detected: must-fix count not decreasing after {N} rounds. Remaining {X} must-fix items require manual intervention.]

Risk Level Behavior Differences

Read risk level from .claude/ecw/session-data/{workflow-id}/session-state.json. If unavailable (standalone invocation), default to P0 (all rounds mandatory).

Risk	Execution Scope	Details
P0	Rounds 1-4 all (mandatory)	Full verification, cannot skip
P1	Rounds 1-3 (mandatory), Round 4 recommended	Correctness mandatory, quality recommended
P2	Round 1 (recommended), can be manually skipped	At least do requirement tracing
P3	Skip	No requirement/plan documents to cross-reference; go directly to hook
Bug	Round 1 variant	Verify fix logic correctly resolves the reported issue without introducing regression

Bug fix Round 1 variant:

• A→B: Bug description issue → Does fix code actually resolve it?
• B→A: Does fix code only change what needs changing, without introducing unrelated changes?
• Additional: On the code path involved in the bug, check for other potential similar issues

Error Handling

Scenario	Handling
Round subagent returns empty or malformed YAML	Record FAILED in findings → append failure marker to impl-verify-findings.md with status: failed → retry once with explicit output format instructions → still fails: coordinator executes that Round inline (fallback to non-subagent mode for that Round only). Previously appended rounds in findings.md remain intact.
All 4 Round subagents fail	Notify user: [DEGRADED: automated verification unavailable] → suggest manual code review or retry
Knowledge file missing (Round 2: business-rules.md, data-model.md, knowledge-summary.md)	Skip Round 2 with [Warning: domain knowledge files not found, Round 2 skipped] → continue with Rounds 1, 3, 4
Requirement/Plan file missing	Skip corresponding Round (1 or 3) with warning → execute remaining Rounds
impl-verify-findings.md write failure	Retry once → still fails: output findings in conversation only, note [Warning: findings file write failed, result held in-session only]
git diff command failure	Verify git state with git status → if not in a git repo or no changes: notify user and exit

Constraints

• Loop cap: Maximum 5 rounds. If must-fix findings remain after 5 rounds, output all unresolved items and suggest user intervention.
• Skippable scenarios: P3 changes; pure formatting/comment changes; degraded scenarios with no requirement/plan/knowledge files to cross-reference (skip with warning).
• Out of scope:
  • Does not check inter-file structural consistency (ecw:cross-review's responsibility, manual optional)
  • Does not check compilation/references/knowledge sync (verify-completion hook's responsibility)
  • Does not analyze business impact scope (ecw:biz-impact-analysis's responsibility)
  • Does not review plan design (ecw:spec-challenge's responsibility, plan phase not implementation phase)

Supplementary Files

• output-templates.md — Per-round findings format, zero-findings format, final pass summary, output constraints
• deviation-patterns.md — 14 common implementation deviation patterns, mapped to verification Round
• prompts/round-checklists.md — Round 1-4 verification checklists (subagent reasoning instructions)
• prompts/common-rationalizations.md — Severity definitions and verification discipline guard (iron law)