# Consistency Check > > - **Type:** Skill - **Install:** `agentstack add skill-pssah4-digital-innovation-agents-consistency-check` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [pssah4](https://agentstack.voostack.com/s/pssah4) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [pssah4](https://github.com/pssah4) - **Source:** https://github.com/pssah4/digital-innovation-agents/tree/main/skills/consistency-check - **Website:** https://pssah4.github.io/digital-innovation-agents/ ## Install ```sh agentstack add skill-pssah4-digital-innovation-agents-consistency-check ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. 2. **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. 3. **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. 4. **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. 5. **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. 6. **ADR contradictions.** No two ADRs cover overlapping topics with opposing decisions. Heuristic: similar titles or matching `triggering-asr` clusters surfaced for human review. 7. **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. 8. **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). 2. **Rule-set drift.** Compare `_devprocess/rules/technical.md` against the actual project state (linter config, test thresholds, framework versions). Surface contradictions for human triage. 3. **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). 4. **ADR duplication check.** Two ADRs covering the same topic at different abstraction levels are flagged for consolidation. 5. **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`. 6. **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. 2. **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. 3. **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. 4. **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. 5. **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. 6. **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](https://github.com/pssah4) - **Source:** [pssah4/digital-innovation-agents](https://github.com/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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-pssah4-digital-innovation-agents-consistency-check - Seller: https://agentstack.voostack.com/s/pssah4 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.