Vet Flow Guide

Vet Flow Guide

Map the implemented user-observable product surface against cases in a write-flow-guide run file. Write a findings report. Stay read-only on product code and the run file. This is judgment, not an ARCH-1 vertical check and not a substitute for dogfood.

The Iron Law

JUDGMENT IS ISOLATED — NOT A LONGER SAME-SESSION §4 SELF-CHECK
FINDINGS ARE CODE-GROUNDED — NO UNINSPECTED SURFACES
REPORT WRITE ONLY — NEVER MUTATE PRODUCT CODE OR THE RUN FILE
PATCHED CASES ARE NOT CLEAN UNTIL A NEW REPORT SAYS SO

1. Inputs

Require a run-file path (.skills/<CODE>/flow-guide.json). Load JSON. If missing or invalid, refuse and point the caller back to write-flow-guide — do not invent cases.

Optional triad (for OOS / persist claims only, never as a substitute for opening product code on implementation claims):

• docs/specs/<feature>/requirements.md
• design.md / tasks.md when present

Done when: run file is loaded or the pass refuses with a clear pointer.

2. Isolation (mandatory)

Perform the judgment pass in a fresh isolated context. Never as a longer same-session §4 self-check after authoring, and never by self-clearing findings without a new report.

Preferred: read-only subagent

1. Fill references/judgment-brief.md with run path, optional triad paths, report path, product paths from design/tasks/known layout, and read-only rules.
2. Dispatch a read-only subagent. The subagent runs the map (step 3) and writes the report (step 5), or returns full report text for the controller to write verbatim — the controller does not re-judge content.

Inline fallback (no subagents)

WHEN no subagents are available, read references/inline-fallback.md beside this file and follow it exactly: state AUTHORING CLOSED — starting isolated vet-flow-guide pass out loud, then load only the brief inputs and run steps 3–5.

Done when: isolation mode is stated and the map runs outside open authoring.

3. Implementation-surface map (product claim)

This skill’s product claim is an implementation-surface map, not authoring hygiene counts.

1. Enumerate user-observable paths and states from opened product code: routes, primary actions, empty/error/role UI the code actually renders, and other UI-exposed states. Skip internal branches, helpers, and service conditionals that never surface to a user.
2. For each surface, search the run file for a corresponding case (setup / try / expect / kind — judgment match, not string equality only).
3. When a shipped user-observable path or state has no corresponding case (including non-happy paths real use can hit on that surface), emit a missing-situation finding with:
   • stable surface_key
   • severity (Critical / Important / Minor) — orders the fix loop only; severity does not soften or clear the dogfood gate
   • situation prose
   • evidence: file / symbol / route / state pointers the reviewer opened (and/or triad when the claim is spec / Out-of-Scope / persist)
4. IF code for a candidate surface was not inspected, THEN do not assert that surface as a missing-situation finding. Skip uninspected candidates.
5. Do not emit non-claim categories (step 4).

Hygiene note (optional, non-blocking)

May list author §1 hygiene observations (requirement-ID coverage, non-happy kinds, schema/kind/status) under a separate report section that does not create open missing-situation findings, does not affect the dogfood gate, and is never this skill’s product claim (see Red Flags).

Done when: every inspected surface is matched or filed; uninspected surfaces are omitted.

4. Explicit non-claims (refuse)

Do not:

This skill does not replace dogfood (run-flow-guide).

Done when: report and prose contain only code-grounded missing-situation findings (plus optional non-blocking hygiene notes).

5. Write the report

Write .skills/<CODE>/vet-flow-guide.md per references/report-schema.md. Required stamp fields:

Finding blocks use integer ids VFG-N (never criterion shape VFG-N.M). Each open finding carries surface_key, severity, situation, evidence.

On re-check: still-open same surface_key reuses the same VFG-N; new misses get the next free integer; resolved misses move to ## Cleared this pass (open list is authoritative for the gate).

Exit by handing report path + open_count to the caller (author fix loop or walkthrough gate).

Done when: report exists on disk with stamp fields and open findings list.

6. Guide-gap fix loop

WHEN the report has open missing-situation findings, read references/guide-gap-loop.md beside this file and follow it exactly: order findings by severity, patch the run file only (never product code) and re-render, re-vet in a fresh isolated pass before any dogfood or “clean” claim, clear a finding only via a new report or a named override, escalate to an isolated fixer subagent at ≥ 5 open findings or ≥ 2 ability areas, and cap at 2 re-judgment cycles before stopping for the human. Non-code-grounded and taste items never keep this loop alive (§4); judgment itself stays read-only throughout — only the report gets written.

Done when: open findings are fixed and re-checked clean, named-overridden, or stopped for the human after 2 re-judgment cycles.

Rationalizations

Red Flags — stop and restart isolation

• Extending authoring todos into “also vet” without AUTHORING CLOSED or a subagent
• Declaring clean without a report file on disk
• Hand-editing an old report’s open list instead of writing a new re-check report
• Hybrid same-session authoring + “vet complete” chat with no report path
• Asserting a surface never opened in this pass
• Writing product code or mutating the run file during judgment
• Titling anything “complete for real users” based on schema/kind counts
• Owning browser drive or FE+BE evidence inside this skill
• Self-clearing findings without a new re-check report
• Patching product code to “close” a guide gap
• Third+ re-judgment cycle without stopping for the human
• Skipping vet because dogfood “will find gaps mid-run”