Flow Verify Skill Skill

Flow Verify Skill

Required Context

Before beginning work, read these files for project-specific guidelines:

.claude/memory-bank/best-practices/contract-first.md
.claude/memory-bank/tech.context.md

Purpose

Verify that cross-boundary wiring is correct across all independently-created systems in a spec group. Catches six categories of wiring bugs: missing imports, unregistered routes, mismatched event names, wrong config references, disconnected handlers, and missing middleware.

Uses a two-layer architecture (following the doc-audit pattern):

flow-verify-checks.mjs (standalone script): Pre-computes source-based wiring analysis, run by the orchestrating agent before dispatch
flow-verifier agent (read-only): Consumes pre-computed results, evaluates carry-forward, produces structured findings

Usage

/flow-verify --stage impl-verify --sg <spec-group-id>        # Standalone gate after implementation
/flow-verify --stage prd-review --prd <prd-path>              # 5th parallel PRD critic
/flow-verify --stage spec-review --sg <spec-group-id>         # Parallel with interface-investigator
/flow-verify --stage post-impl --sg <spec-group-id>           # Comprehensive coverage report

Parameters

| Parameter | Type | Required | Default | Description | | --------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------- | | stage | string | Yes | -- | Stage mode: prd-review, spec-review, impl-verify, post-impl | | sg | string | Yes* | -- | Spec group ID (required for all stages except prd-review) | | prd | string | No | -- | PRD file path (used for prd-review stage) | | scope | string | No | full | Verification scope: full or diff (stage-dependent — see below) | | diff_base | string | No | main | Git ref used as diff base when scope=diff (e.g., branch base ref for PR diffs) | | fallback_enum | string | No | none | Diff-fallback strategy when diff_base unresolvable: none, head-1, full-repo |

Stage → Scope Mapping (as-003 / REQ-006)

The dispatcher applies an automatic stage → scope mapping when scope is not explicitly overridden:

| Stage | Auto-Scope | Rationale | | ------------- | ---------- | ---------------------------------------------------------------------------------------- | | prd-review | full | Comprehensive review of PRD boundaries; no diff context yet. | | spec-review | full | Spec-stage review covers all integration interfaces; no implementation diff yet. | | impl-verify | diff | Narrows verification to changed files for efficiency; full-repo unnecessary post-impl. | | post-impl | diff | Comprehensive coverage against the merged diff; pairs with diff_base from branch base. |

At impl-verify and post-impl, the dispatcher additionally passes diff_base (default main) and fallback_enum (default none). At prd-review and spec-review, the dispatcher passes scope: "full".

Stage-scope validation: scope: "diff" is rejected at prd-review / spec-review with a structured stage-scope mismatch error (see agent prompt § Stage-Scope Validation Rule). Callers attempting scope: "diff" at those stages receive a rejection without dispatching the agent work.

Backward compatibility: scope: "full" remains the safe default across all stages. Pre-as-003 dispatches that pass no scope continue working unchanged.

Workflow Applicability

oneoff-spec: All four stages applicable
oneoff-vibe: NOT dispatched (skip entirely)

Pre-Flight Challenge

Before beginning flow verification work, address these operational feasibility questions:

Does the spec group have a defined scope boundary for in-scope flow identification?
Is the carry-forward file (flow-findings.json) accessible? (Missing is normal for first stage)
Are modified files discoverable from git history or the spec group directory?

If any question cannot be answered from available context, surface it as a finding -- do not skip.

Execution Flow

Stage: impl-verify (Standalone Gate)

This is the highest-value stage and the most critical for catching wiring bugs.

Step 1: Pre-Computation (Main agent runs this)

node .claude/scripts/flow-verify-checks.mjs --sg <spec-group-id> --stage impl-verify

This produces .claude/specs/groups/<sg>/.flow-verify-precomputed.json with:

Source-based wiring analysis (imports, exports, event strings, config references)
Six wiring check results (routes, events, config, imports, handlers, middleware)
Coverage indicator (full/partial)
Unchecked files array (when caps exceeded)

Step 2: Agent Dispatch

Dispatch the flow-verifier agent with stage impl-verify, providing the pre-computed results path and spec group ID.

Step 3: Gate Decision

The agent returns a gate output:

block: Any Critical finding present. Workflow halts until resolved or human overrides via gate-override.json
warn: No Critical but High findings present, OR coverage is partial. Requires human acknowledgment
pass: Only Medium/Low findings with full coverage. Workflow proceeds to unifier

Stage: prd-review (5th Parallel Critic)

Dispatched during /prd Phase 2 (critique loop) in parallel with the four existing PRD critics. Checks whether the PRD describes all cross-boundary connections, data handoffs, and event flows.

No pre-computation needed -- the agent reads the PRD directly.

Stage: spec-review (Parallel with Investigator)

Dispatched during /investigate convergence loop in parallel with the interface-investigator. Checks spec integration interfaces, subgraph completeness, and event/data contract coverage.

No pre-computation needed -- the agent reads spec artifacts directly.

Findings feed into the investigation convergence loop and are deduplicated with investigator findings by integration_point key.

Stage: post-impl (Comprehensive Report)

Dispatched after unifier passes, before code review. Produces:

Comprehensive flow coverage report (flow-coverage.yaml)
Wiring diagrams (Mermaid .mmd files)
Summary of fully verified flows, flows with gaps, and undocumented flows

Pre-computation required (same as impl-verify).

Carry-Forward Mechanism

Findings carry forward between stages via .claude/specs/groups/<sg>/flow-findings.json:

Each stage appends its findings to the carry-forward file
Later stages read prior findings for context
Persisting gaps are elevated by one severity level per stage transition (cap: Critical)
Re-runs during convergence loops replace (not append) prior findings for the same stage
Only the flow-verifier agent writes to this file (single writer, multiple readers)

Gate Override

When impl-verify returns block, the human may override using:

// .claude/coordination/gate-override.json
{
  "overrides": [
    {
      "gate": "flow-verify",
      "session_id": "<current-session>",
      "timestamp": "<ISO timestamp>",
      "rationale": "Reviewed Critical finding FLOW-IMPL-001, determined false positive due to..."
    }
  ]
}

Overridden findings are marked status: "human-overridden" in the carry-forward file.

Output Artifacts

| Artifact | Path | Stage | | ---------------------- | --------------------------------------------------------- | ---------------------- | | Pre-computed analysis | .claude/specs/groups/<sg>/.flow-verify-precomputed.json | impl-verify, post-impl | | Carry-forward findings | .claude/specs/groups/<sg>/flow-findings.json | All stages | | Flow coverage report | .claude/docs/structured/flows/flow-coverage.yaml | post-impl | | Wiring diagram | .claude/docs/structured/generated/flow-wiring-<sg>.mmd | post-impl |

Integration with Other Skills

Before: /implement (all ACs implemented), /investigate (spec-review stage)
After: /unify (impl-verify gate passes), /code-review (post-impl report available)
Parallel with: PRD critics (prd-review), interface-investigator (spec-review)
Replaces: Practice 4.5 inline integration checks (subsumed by impl-verify stage)

Agent Skills: Flow Verify Skill

Install this agent skill to your local

Skill Files