Consistency Check

Consistency Check

This skill treats the V-Model artifacts as a graph. Nodes are artifacts (BA sections, Epics, Features, Success Criteria, ADRs, arc42 sections, PLANs, Backlog items, Code files). Edges are references (Epic→Feature, Feature→ADR, Feature→Code via source paths, BL-Item→Feature, and so on). The check answers one question: is the graph complete and consistent, or do we have orphans, dead links, and semantic drift?

The skill is called by other skills at the end of each phase, or directly by the user when a health check is due.

Writing style: Every artifact this skill writes follows the rules in skills/project-conventions/SKILL.md under "Writing style". No em dashes, no AI vocabulary, ASCII for umlauts if the existing project convention uses ASCII.

Three modes

• Mode A (syntactic, default): fast, no LLM, runs on phase-end

triggers and pre-commit hooks.

• Mode B (semantic, on-demand): agent-based, runs before release

or on explicit --deep.

• Mode C (interactive fix-loop): guided fix workflow with

per-finding AskUserQuestion, Pro/Con suggestions, skip and custom-message options. Triggered by --fix-interactive or after a pre-commit hook block.

Mode reference

Mode A: Syntactic check (default, fast, no LLM)

Runs on every Phase-End trigger. Uses Grep + filesystem probes only. Costs near zero.

Checks (8 quick-check items):

1. Dead links. Every Markdown link to a project-internal path

(_devprocess/..., src/..., docs/...) points to an existing file.

1. Backlog completeness. Every artifact file under

_devprocess/requirements/, _devprocess/architecture/, _devprocess/implementation/plans/, _devprocess/requirements/fixes/, and _devprocess/requirements/improvements/ has exactly one row in the backlog. No artifact without a row, no row without an artifact.

1. Backlog as single source. Artifact frontmatter does NOT carry

status: or phase: fields. The backlog row is authoritative. Frontmatter that duplicates these fields gets flagged.

1. Spec references valid. Every Feature references a real Epic

ID. Every Backlog Refs entry resolves to an existing row or file. Every PLAN's feature-refs, adr-refs, fix-refs, and imp-refs resolve.

1. ADR references valid. Every ADR ID listed in a FEATURE's

adr-refs, in arc42 Par. 9 table, in JSDoc headers, or in src/ARCHITECTURE.map resolves to an existing ADR file.

1. ADR contradictions. No two ADRs cover overlapping topics with

opposing decisions. Heuristic: similar titles or matching triggering-asr clusters surfaced for human review.

1. ADR abstraction rule. No ADR contains code paths

(src/... strings, file basenames, line numbers, method signatures) in the core sections (Context, Decision Drivers, Considered Options, Decision, Consequences). Code paths in the ## Implementation Notes appendix are exempt.

1. Backlog graph health. Every Refs entry in the backlog points

at an existing row. The graph derived from the Refs columns is acyclic (Epic -> Feature -> Plan -> Fix forms a DAG).

Auto-fix mode

When run with --fix (or when called by another skill with autofix=true), the syntactic check repairs the following drift types automatically, without asking:

• Frontmatter status: or phase: field present: REMOVE it.

Backlog row is the single source of truth. The fix lifts the current value from the artifact into the backlog row only if no row exists yet; otherwise it just removes the duplicate. Reverse-engineering exception (graph-invariants N-10 / N-11): values starting with Anticipated, Observed, Inferred, or Draft (reverse-engineered, ...) are validation markers that /business-analysis strips after validation. The autofix keeps them and only removes generic lifecycle status / phase entries.

• Backlog row missing for an existing artifact file: create the row

with status: Ready, phase: Building defaults, place under the matching Epic section.

• Artifact file missing for a backlog row: leave the row, flag for

human triage (the row may be a placeholder or outdated entry).

• Dashboard counts differ from computed totals: rewrite the

dashboard table.

• ARCHITECTURE.map row points at a missing entry-point file: flag,

do not auto-delete. Renames may have happened.

The auto-fix report lists what was changed. Items that cannot be auto-fixed (orphan ADR, dead link, ADR abstraction violation) are reported and left for the user.

Mode B: Semantic check (on-demand, agent-based)

Runs on explicit user request or before a release. Uses subagents to read paired artifacts and judge whether their content remains consistent. Costs measurable agent-time.

Checks (6 deep-check items):

1. Spec-code coherence. For every Feature with status Done in

the backlog, sample-check whether the Success Criteria described in the FEATURE spec are plausibly verifiable in the code (sampling, not exhaustive).

1. Rule-set drift. Compare _devprocess/rules/technical.md

against the actual project state (linter config, test thresholds, framework versions). Surface contradictions for human triage.

1. Orphan artifacts. Specs without code (FEATURE Done in

backlog but no entry-point in src/ARCHITECTURE.map); code without spec (entry-point in src/ARCHITECTURE.map with no matching FEATURE backlog row).

1. ADR duplication check. Two ADRs covering the same topic at

different abstraction levels are flagged for consolidation.

1. Map completeness. Every module under src/ that owns

substance has an ARCHITECTURE.map entry. Triggers: more than 3 source files in a directory, or any directory with a README.md.

1. Backlog graph render. Produce a mermaid or JSON graph from

the backlog Refs columns, surface orphan nodes (no incoming or outgoing edges) and status mismatches (e.g. PLAN Done but parent FEATURE still In Progress).

Each finding includes file path, row reference, and enough context to locate the issue. Findings that cannot be auto-fixed become BL items in the Standalone Items section with Source = CONSISTENCY-CHECK.

Mode C: Interactive fix-loop (on-demand or post-block)

Triggered by /consistency-check --fix-interactive or by the pre-commit hook when Mode A leaves non-auto-fixable findings. The loop picks up the latest run from .git/consistency-check.last-run.json (Mode A always writes this file) and walks every finding with the user, one by one.

Resume contract. The findings file persists across Claude Code sessions. If the user exits Claude mid-loop, the next /consistency-check --fix-interactive invocation reads the same file and continues at the first unresolved finding. Resolved findings are marked status: "fixed" or status: "skipped" in the JSON; the loop never re-asks about them. The file is deleted only after the loop completes and the user confirms the commit.

Universal interaction rules (the "never leave the user alone" contract). Every step in this loop ends with one AskUserQuestion that satisfies all of:

• One short recommendation sentence ("Empfehlung: A, weil ...").
• Two to four concrete options, each with a one-line Pro: and

one-line Con: block.

• A Skip option that defers the finding without losing it.
• A Custom option ("eigene Anweisung schreiben") so the user can

always override.

• The recommendation and the option list are derived from the

current finding plus the project state, not boilerplate.

This rule is invariant. The loop never returns control to the user without an explicit next-step question. If a step has no decision left to make (e.g. all findings resolved), the question still asks about the next workflow step (commit, push, /testing, /release).

Loop structure (six phases):

1. Load. Read .git/consistency-check.last-run.json. If absent

or empty, run Mode A first and then continue.

1. Triage. AskUserQuestion: which strategy (sequential, by

severity, by class, batch-fix-only, trust-mode auto-approve, custom). Recommendation adapts to finding count: sequential up to 10, by-severity 11+, trust-mode when the user explicitly says "mach wie du denkst" or selects it.

Trust mode (auto-approve all): the user delegates all fix decisions to the agent. The loop applies the recommended option for every finding without asking, except when:

• A finding's three options have no clear recommendation

(recommendation field empty in the suggestion bundle)

• A fix would touch shared infrastructure (CI configs, hooks,

governance code) -- always escalate

• A fix would delete substance (more than just a Status

duplicate or dead link) -- escalate to confirm

In trust mode, after every batch of 10 fixes the loop posts a one-line progress update so the user sees movement. At the end it produces a complete audit log: per-finding the chosen option, the resulting diff hunk reference, and any escalations.

1. Per-finding loop. For each unresolved finding, AskUserQuestion

with file:line pointer, finding text, two to four concrete fix options with Pro/Con, plus Skip and Custom. Recommendation names the option and gives the reason from project state.

1. Re-check. Run Mode A again. List remaining findings (Skips

and any new findings produced by fixes). AskUserQuestion: how to handle remaining findings (file as backlog items with Source=CONSISTENCY-CHECK, commit anyway via --no-verify, return to skips, custom). Recommendation defaults to backlog-filing.

1. Commit. Build the commit message from the resolved findings

list, show it to the user, AskUserQuestion: confirm message, edit message, or cancel. Recommendation is "confirm" when the message accurately summarizes the fixes.

1. Follow-up. AskUserQuestion: what next (push, /coding,

/testing, /security-audit, /release, custom). Recommendation follows the V-Model checklist (after /coding -> /testing, after /testing -> /security-audit, before release -> Mode B semantic check).

Fix actions per finding type. The loop dispatches to specific fix patterns based on the finding's type field:

| Finding type | Auto-fix candidates surfaced as options | |---|---| | dead-link | Remove, mark planned with FEAT-ref, correct path | | adr-abstraction-violation | Move path to ## Implementation Notes appendix, move path to src/ARCHITECTURE.map, replace path with concept name | | orphan-adr | Mark Superseded with reference, mark Deprecated, link from a feature | | orphan-feature | Assign to existing epic, create new epic, mark Planned | | feature-without-sc | Add [AWAITING BA] placeholder, write SC inline, defer | | source-path-broken | Update path, mark feature Planned, remove path entry | | frontmatter-status-duplicate | Always auto-fixed in Mode A; only surfaces here if auto-fix failed | | status-coherence-breach | Open the owning phase skill (/business-analysis for BA Draft, /requirements-engineering for RE-side BA promotion, /architecture for ADR Proposed), Defer (file as backlog item with Source=CONSISTENCY-CHECK), Skip with reason. No direct edit option: status promotion is a semantic claim and belongs in the phase skill. | | feature-activation-path-missing | Open /requirements-engineering to add the Activation Path entry, Demote FEATURE backlog status from Done to In Progress, Defer (file as backlog item with Source=CONSISTENCY-CHECK), Skip with reason. No direct edit option: subtype-aware contract is owned by /requirements-engineering. | | stub-without-fix-row | Open /coding to create the missing FIX-row, Remove the stale FIXME marker (only if the stub has been resolved in code), Skip with reason. | | fix-without-stub-evidence | Open /coding to add the FIXME marker at the stubbed code location, Resolve the FIX (mark Done if the stub is gone), Defer, Skip with reason. | | artefact-cap-exceeded | Shrink the artefact to within the cap, Move detail to a child artefact (BA -> Mini-BA, FEATURE -> PLAN), Add a ## Reasoned exception block at the top, Skip with reason. | | forbidden-section-resurfaced | Remove the section / frontmatter key, Move substance into the BACKLOG row, Open the owning phase skill, Skip with reason. |

Output of the loop. The loop writes a single audit row in _devprocess/context/METRICS.md under "Consistency-Check Runs" with: timestamp, mode (C), findings-total, fixed, skipped, deferred- to-backlog, and the commit SHA when applicable.

Invocation

• /consistency-check with no args: runs Mode A on the current

project root, reports results, and writes .git/consistency-check.last-run.json.

• /consistency-check --fix: Mode A with auto-fix enabled (no user

interaction). Used by the pre-commit hook before falling back to Mode C if findings remain.

• /consistency-check --fix-interactive: Mode C interactive

fix-loop. Reads the last-run file and walks the user through.

• /consistency-check --deep or with user saying "semantic check":

runs Mode A + Mode B.

• /consistency-check --view or user says "zeig mir den Graph",

"show me the graph": runs Mode A and opens the interactive graph viewer (see Viewer-Tool below).

• Called from another skill: the calling skill passes a scope

argument (e.g. scope=feature:FEAT-NN-19 to check only a single feature's neighbourhood).

• Called from pre-commit hook: hook runs --fix first, then if

findings remain prompts the user to launch --fix-interactive.

Tooling

The syntactic checker (Mode A) and the pre-commit hook live in tools/ of this DIA repo:

• tools/consistency-check.py -- project-agnostic Mode A driver.

Auto-detects the repo root via git rev-parse --show-toplevel and expects the standard DIA layout (_devprocess/, optional src/). Optional dia.config.json in the project root overrides defaults.

• tools/git-hooks/pre-commit -- pre-commit hook template that runs

the Mode A driver, then on findings asks the user (y/N) whether to launch the interactive Mode C fix-loop in Claude Code.

• tools/install-git-hooks.sh -- installer. Run from the target

project's repo root: bash /tools/install-git-hooks.sh. Copies the script to the target's .git/hooks-data/ and installs the pre-commit hook into .git/hooks/pre-commit.

Mode B (semantic) and Mode C (interactive fix-loop) are orchestrated inside Claude Code by this skill, not by the script.

Caps

N-20 reads the per-artefact line caps from this table. The single source of truth is skills/project-conventions/SKILL.md#canonical-specs (Reader budget); the table below is a mirror and must be kept hand-aligned with the source. The script holds the same values in ARTIFACT_CAPS near the top of tools/consistency-check.py.

| Cap key | Cap (lines) | Counting boundary | |---|---|---| | project-ba | 200 | full file | | epic-ba | 120 | full file | | feat-ba | 60 | full file | | ba-mini | 40 | full file | | exploration-board | 70 | full file | | epic | 35 | full file | | feature | 65 | full file | | backlog-header | 80 | up to ## Active Epics | | architect-handoff | 60 | full file | | adr | 50 | full file (Implementation Notes appendix exempt by convention) | | arc42-poc | 65 | full file | | arc42-mvp | 100 | full file | | plan-context | 55 | full file | | plan | 50 | up to ## Change Log | | fix | 28 | full file | | imp | 26 | full file | | audit | 55 | full file (finding tables exempt by convention) | | metrics | 50 | full file |

Tolerance: a file is flagged only when it exceeds cap * 1.10. A top-level ## Reasoned exception heading suppresses the finding.

Viewer tool (for team meetings and navigation)

The graph is NOT persisted in a separate file. It exists implicitly in the backlog Refs columns and Markdown references; it is generated on-de

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pssah4
• Source: pssah4/digital-innovation-agents
• License: MIT
• Homepage: https://pssah4.github.io/digital-innovation-agents/

Install and usage instructions live in the source repository linked above.