--- name: ce-standards-gap-analyzer description: > Analyze standards compliance by interpreting the standards's intent, verifying that implementation and RTD satisfy every decision, and producing a dated gap report with only unresolved items. --- # CE Standards Gap Analyzer You are verifying that the **intent and decisions** of a given STD are fully realized in code and documentation. Your job is not keyword grepping — it is substantive compliance analysis. --- ## Inputs - STD identifier (e.g. `STD-004`), or `all` to sweep every STD in the appendix. - Repository files (source code, tests, docs) accessible in workspace. --- ## Phase 1 — Understand the STD intent 1. **Read the full STD text** (`docs/standards/STD-XXX-*.md`). Extract: - **Decisions** — what the STD mandates, forbids, or constrains. - **Requirements** — concrete deliverables (APIs, contracts, invariants, enforcement mechanisms, documentation, tests). - **Rationale** — why these decisions were made. This is needed to judge whether an implementation satisfies the spirit, not just the letter. - **Scope** — which modules, subsystems, or surfaces the STD governs. 2. Build a **checklist of required outcomes** from the decisions. Each outcome is a testable statement, e.g.: - "Plugin trust flags must be immutable after registration." - "RTD must document the fallback chain." - "CI must enforce the two-release deprecation window." ## Phase 2 — Verify implementation against intent 3. For each required outcome, **search and read the codebase** (`src/`, `tests/`, configuration files): - Read the relevant source files. Understand what the code actually does and whether it satisfies the STD requirement. - Check for invariant enforcement (assertions, validators, guards) where the STD requires them. - Check for correct API surfaces, signatures, and contracts where the STD specifies them. - Check for tests that exercise the required behavior. 4. For each required outcome, **check RTD and documentation** (`docs/`) when the STD has documentation requirements: - Verify that docs describe the behavior accurately and consistently with the implementation. - Flag docs that contradict the code or the STD text. - Flag missing documentation for STD-mandated surfaces. ## Phase 3 — Classify and score gaps 5. For each required outcome that is **not fully satisfied**, record a gap: - Violation impact (1–5): how seriously the gap violates the STD intent. - Code scope (1–5): breadth of code affected. - Unified severity = impact × scope. - One-line recommendation with file/line pointers where evidence was found (or expected but missing). 6. Mark outcomes that **are fully satisfied** as completed — these will be purged from the output (see Phase 4). ## Phase 4 — Update the STD status appendix The output format and rules are defined in the **STD status appendix** (comes after the ADR status appendix) heading of `docs/improvement/RELEASE_PLAN_v1.md`. The appendix states: > This appendix lists only unresolved gaps per STD. STDs with no open gaps > show a clear compliance verification line (date-stamped). Tables use the > project's severity axes: Violation impact (1–5) × Code scope (1–5) = > Unified severity. Follow these rules exactly when writing or updating appendix sections: 7. **Purge completed gaps.** When updating an existing appendix section: - **Remove every row whose gap is resolved.** Do not keep completed rows with zeroed-out scores — delete them entirely. - If a table mixes completed and open rows, rewrite it with **only the remaining open rows**, ranks renumbered from 1. - If **all** rows are completed, **replace the entire table** (header, separator, data rows) with a single compliance verification line. 8. **Only unresolved gaps appear.** Never list completed, resolved, or zeroed-out rows in the table. 9. **Date stamp — mandatory on every update.** Every time the appendix is updated (single STD or full sweep), stamp today's date: - Compliance lines use format: `**Compliance verification (YYYY-MM-DD):** Reviewed code and RTD — no STD-XXX gaps found; STD-XXX is fully compliant. No further action required.` - Gap tables: add `_Last gap analysis: YYYY-MM-DD_` immediately above the table. 10. **If NO gaps remain** the compliance verification line must be unambiguous — it replaces the entire table and makes clear that no further action is required. --- ## Key principles - **Intent over keywords.** Do not rely on grepping for `TODO` or `COMPLETED`. Read the STD decisions, understand what they require, and verify that code and docs deliver. A missing `TODO` does not mean compliance; present code does not mean the STD intent is satisfied. - **Substance over ceremony.** A gap exists when implementation diverges from what the STD decided — not when a keyword is absent. A gap is closed when code and docs genuinely satisfy the requirement — not when someone wrote `COMPLETED` next to it. - **Conservative severity.** Prefer conservative estimates when evidence is ambiguous. - **Evidence-based.** Every gap claim must cite specific files and lines (or their absence). Every compliance claim must cite the evidence that satisfies the STD requirement. - **Keep Standards status appendix tidy.** Status reports must be placed correctly in the order under the correct header in the standards status appendix. No duplicate entries per standard allowed. --- ## Files to read ``` docs/standards/STD-XXX-*.md ← the STD itself (primary source of intent) docs/improvement/RELEASE_PLAN_v1.md ← appendix to update with gap results src/ ← implementation evidence tests/ ← test coverage of STD requirements docs/ ← RTD evidence (when STD has doc requirements) ``` --- ## Notes and constraints - This skill is an evidence-gathering assistant, not an authoritative arbiter. Impact/scope ratings are suggestions for STD owner review. - The date is always stamped — there is no opt-out. - When sweeping all STDs, process each section independently and apply the same four phases to every one.