---
description: Perform a read-only consistency analysis across spec.md, plan.md, tasks.md, contracts/modules.md, and ADR sources for the active superset-tools feature. Covers UX Contract Traceability, ATTN Rules Compliance, decision-memory continuity, and component reuse analysis.
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Required Skills

MANDATORY USE `skill({name="semantics-core"})`, `skill({name="semantics-contracts"})`, `skill({name="semantics-svelte"})`.

## Goal

Identify inconsistencies, ambiguities, coverage gaps, decision-memory drift, UX contract gaps, ATTN-rules violations, and **component reuse opportunities** across the feature artifacts **before implementation proceeds**. This command MUST run only after `/speckit.tasks` has produced a complete `tasks.md`.

## Operating Constraints

**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up edits).

**Constitution Authority**: `.specify/memory/constitution.md` is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks — not dilution, reinterpretation, or silent ignoring of the principle.

## Execution Steps

### 1. Initialize Analysis Context

Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for `FEATURE_DIR` and `AVAILABLE_DOCS`. Derive absolute paths:

- `SPEC` = `FEATURE_DIR/spec.md`
- `PLAN` = `FEATURE_DIR/plan.md`
- `TASKS` = `FEATURE_DIR/tasks.md`
- `CONTRACTS` = `FEATURE_DIR/contracts/modules.md` (when present)
- `ADR` = `docs/adr/*.md` (repo-global ADR sources when referenced)

Abort with an error message if any required file is missing (instruct the user to run the missing prerequisite command).

### 2. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

**From `spec.md`:**
- Overview / Context
- Functional Requirements
- Non-Functional Requirements
- User Stories with acceptance criteria
- Edge Cases (when present)

**From `plan.md`:**
- Architecture / stack choices
- Data Model references
- Phases / milestones
- Technical constraints
- ADR references or emitted decisions
- Component inventory (Svelte components, Screen Models)

**From `tasks.md`:**
- Task IDs with checkbox status
- Descriptions and exact file paths
- Phase grouping and story labels (`[USx]`)
- Parallel markers (`[P]`)
- Inlined contract constraints (`@PRE`, `@POST`, `@SIDE_EFFECT`, `@TEST_EDGE`)
- Inlined ADR guardrails (`@RATIONALE`, `@REJECTED`)
- Referenced UX states and component names

**From `contracts/modules.md` (when present):**
- All `#region` / `[DEF:...]` contract headers
- Complexity tiers (`[C:N]`)
- Type annotations (`[TYPE ...]`)
- Domain grouping (`@defgroup`, `@ingroup`)
- `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY` annotations
- `@UX_TEST`, `@UX_REACTIVITY` annotations
- `@RATIONALE`, `@REJECTED` decision-memory entries
- `@RELATION` edges
- `@PRE`, `@POST`, `@INVARIANT`, `@DATA_CONTRACT` entries

**From ADR sources:**
- ADR IDs and status
- `@RATIONALE` — accepted paths
- `@REJECTED` — forbidden paths
- `@RELATION DEPENDS_ON` edges to other ADRs

**From codebase inventory (via axiom MCP):**
- Run `axiom_search({operation="status"})` — confirm axiom index is FRESH and ready. Abort reuse analysis if stale.
- Run `axiom_search({operation="workspace_health"})` — get total contract count, orphan/unresolved metrics. When the existing component inventory query is incomplete, flag findings as LOW confidence and fall back to file-path grep.

**From constitution (`.specify/memory/constitution.md`):**
- All MUST-level principles (I-VIII)
- Verification gates
- Development workflow steps

### 3. Build Semantic Models

Create internal representations (do NOT include raw artifacts in output):

- **Requirements inventory**: Each functional + non-functional requirement with a stable slug key (derive from imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
- **User story inventory**: Discrete user actions with acceptance criteria
- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns)
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
- **Decision-memory inventory**: ADR ids, accepted paths, rejected paths, and the tasks/contracts expected to inherit them
- **UX contract inventory**: Per-component map of declared `@UX_STATE` names, `@UX_FEEDBACK` mechanisms, `@UX_RECOVERY` paths, and `@UX_TEST` scenarios from both `contracts/modules.md` and `tasks.md`
- **ATTN rules snapshot**: For each contract in `contracts/modules.md`, record: anchor line count (ATTN_1), ID hierarchy depth (ATTN_2), `[SEMANTICS ...]` keywords and `@ingroup` presence (ATTN_3), estimated line count (ATTN_4)
- **Existing component inventory**: Built via axiom MCP by extracting keywords from the planned component list (services, Svelte components, plugins, utilities referenced in spec/plan/tasks) and searching:
  - `axiom_search({operation="search_contracts", query=<planned_service_name>})` for backend services
  - `axiom_search({operation="search_contracts", query=<planned_component_name>})` for Svelte components
  - `axiom_search({operation="search_contracts", query=<planned_plugin_name>, fuzzy:true})` for plugins
  - For each hit, record: `contract_id`, `contract_type`, `file_path`, `@BRIEF`, `complexity`, `relations` — these form the existing component catalog

### 4. Detection Passes (Token-Efficient Analysis)

Focus on high-signal findings. **Limit to 50 findings total**; aggregate remainder in overflow summary. Generate stable IDs prefixed by category initial.

---

#### A. Duplication Detection

- Identify near-duplicate requirements within `spec.md`
- Flag tasks that duplicate work across different phases without explicit dependency
- Mark lower-quality phrasing for consolidation

#### B. Ambiguity Detection

- Flag vague adjectives lacking measurable criteria: "fast", "scalable", "secure", "intuitive", "robust", "reliable", "performant"
- Flag unresolved placeholders: `TODO`, `TKTK`, `???`, `<placeholder>`, `TBD`, `TBC`
- Flag acceptance criteria without a measurable outcome (e.g., "works correctly")

#### C. Underspecification

- Requirements with verbs but missing object or measurable outcome
- User stories missing acceptance criteria alignment
- Tasks referencing files or components not defined in `spec.md` or `plan.md`
- Tasks lacking exact file paths (violates tasks.md generation rules)

#### D. Constitution Alignment

- Any requirement or plan element conflicting with a MUST principle (I-VIII)
- Missing mandated sections or quality gates from constitution
- Feature that contradicts ADR-guarded architectural decisions without `<ESCALATION>`

#### E. Coverage Gaps

- Requirements with **zero** associated tasks
- Tasks with **no** mapped requirement or user story
- Non-functional requirements (performance, security, RBAC) not reflected in tasks

#### F. Inconsistency

- **Terminology drift**: same concept named differently across `spec.md`, `plan.md`, `tasks.md` (e.g., "migration plan" vs "transfer config" vs "export bundle")
- **Entity mismatches**: data entities referenced in `plan.md` but absent in `spec.md` (or vice versa)
- **Task ordering contradictions**: integration tasks scheduled before foundational setup tasks without dependency note
- **Conflicting requirements**: two requirements that cannot both be satisfied (e.g., "no database" vs "persist user preferences")
- **Rust/MCP path contamination**: task or plan references `.rs` files, `cargo`, `src/server/`, or MCP server paths in a Python/Svelte project

#### G. Decision-Memory Drift

- ADR exists in `docs/adr/` with a `@REJECTED` path, but `tasks.md` schedules work implementing that rejected path
- ADR exists with a `@RATIONALE`-guarded decision, but no downstream task carries a corresponding guardrail
- Task carries a `@RATIONALE` / `@REJECTED` guardrail with no upstream ADR or plan rationale
- Decision recorded in `contracts/modules.md` (`@RATIONALE` / `@REJECTED`) is not propagated to any task in `tasks.md`
- `@REJECTED` path in `plan.md` or ADR is contradicted by later spec or task language without explicit `<ESCALATION>` decision revision

#### H. UX Contract Traceability

Validate Svelte component UX contracts across `contracts/modules.md` and `tasks.md`. Reference `semantics-svelte` §II (UX Contracts) and §IIIa (Reactive Screen Models).

| # | Rule | Severity | What to check |
|---|------|----------|---------------|
| **H1** | **Missing UX Triplet** | MEDIUM (display) / HIGH (interactive) | Component contract in `contracts/modules.md` has `@UX_STATE` but is **missing** `@UX_FEEDBACK` and/or `@UX_RECOVERY`. For interactive components (forms, mutations, migrations, actions): severity HIGH. For display-only (badges, status labels): MEDIUM. |
| **H2** | **State Name Drift** | HIGH | The set of state names declared in `@UX_STATE` for a component in `contracts/modules.md` **differs** from the state names referenced in that component's task in `tasks.md`. Example: contract says `loading/loaded/error`, task says `fetching/ready/failed`. |
| **H3** | **Orphan UX Test** | MEDIUM | A `@UX_TEST` scenario references a state name that is **not declared** in the corresponding `@UX_STATE` list. Example: `@UX_TEST: Saving -> ...` but `@UX_STATE` only declares `idle/loading/loaded/error`. |
| **H4** | **Untested UX State** | MEDIUM | A state declared in `@UX_STATE` has **no** corresponding `@UX_TEST` scenario. User-facing states without test coverage create blind spots for the browser Judge Agent. |
| **H5** | **Missing UX Contract for Component** | MEDIUM | A frontend task in `tasks.md` references a Svelte component (`.svelte` file) but `contracts/modules.md` has **no** UX annotations (`@UX_STATE` / `@UX_FEEDBACK` / `@UX_RECOVERY`) for that component. |
| **H6** | **Incomplete Recovery Path** | MEDIUM | `@UX_STATE` includes error-like states (`error`, `timeout`, `network_down`, `save_error`, `lookup_error`) but `@UX_RECOVERY` is **absent or empty**. Every error state MUST have a user recovery path. |
| **H7** | **Inconsistent UX Annotation Style** | LOW | Within the same `contracts/modules.md`, UX annotations use mixed formats: some in HTML comments (`<!-- @UX_STATE ... -->`), some as bare tags (`@UX_STATE: ...`). Pick one style for the entire file. |
| **H8** | **Missing Model-First Pattern** | MEDIUM | `plan.md` describes a screen with cross-widget logic (filters affecting lists, multi-step forms, pagination with search) but `contracts/modules.md` contains **no** `[TYPE Model]` contract. Complex screens MUST use the Screen Model pattern (`semantics-svelte` §IIIa). |

#### I. ATTN Rules Compliance

Validate that all contracts in `contracts/modules.md` comply with the Attention Architecture rules from `semantics-core` §VIII. Contracts that violate these rules become invisible to the model after context compression — causing downstream hallucination during implementation.

| # | Rule | Severity | What to check |
|---|------|----------|---------------|
| **I1** | **ATTN_1 — Split Anchor** | HIGH | Contract opening anchor spreads across **multiple lines**. ID, `[C:N]`, `[TYPE TypeName]`, `[SEMANTICS tags]` MUST be on ONE line. CSA 4× pooling compresses multi-line anchors into separate KV records — the contract becomes invisible. Check: `#region Id [C:N] [TYPE Type] [SEMANTICS t1,t2]` is all on ONE line. |
| **I2** | **ATTN_2 — Flat ID** | HIGH (C3+) / MEDIUM (C1-C2) | Contract ID is a single word without dot-separated domain hierarchy. After HCA 128× compression, `login_handler` is noise; `Core.Auth.Login` survives. Required: at least 2 hierarchy levels (`Domain.Name`) for C3+. For C1/C2 inside a hierarchical parent, single-level may be acceptable. |
| **I3** | **ATTN_3 — Missing Semantic Grouping** | MEDIUM | Two contracts in the same domain use **different** primary keywords in `[SEMANTICS ...]`. Example: one auth contract has `[SEMANTICS login]`, another has `[SEMANTICS authentication]` — DSA Lightning Indexer cannot group them. Also check: module has `@defgroup` but children lack `@ingroup` (or vice versa). |
| **I4** | **ATTN_4 — Boundary Overrun** | MEDIUM | Estimated contract length exceeds **150 lines** or module exceeds **400 lines**. Violates INV_7 (`semantics-core` §I) and sliding window visibility (`semantics-core` §VIII ATTN_4). Flag contracts/modules that appear to be over the limit based on content density. |
| **I5** | **Missing Complexity Tag** | CRITICAL | Contract header lacks `[C:N]` complexity tier annotation. Violates INV_1: every contract MUST have a `#region`/`#endregion` with explicit complexity. Without `[C:N]`, the semantic index cannot classify the contract. |
| **I6** | **Missing Type Tag** | HIGH | Contract header lacks `[TYPE TypeName]` annotation. The type (`Module`, `Function`, `Class`, `Component`, `Model`, `ADR`, etc.) is required for the semantic index to route relations correctly. |

#### J. Component Reuse Analysis

Detect existing codebase components that the feature could reuse, extend, or adapt instead of writing new code from scratch. Use axiom MCP for semantic contract search, neighborhood queries, and impact analysis.

First, build a **planned component list** by extracting from spec.md, plan.md, and tasks.md every named service class, Svelte component, utility module, plugin, API route, or data model that the feature intends to create.

Then apply the rules below. For each planned component, determine which existing contract (by `contract_id` / `file_path`) it overlaps with and what action is appropriate.

| # | Rule | Severity | Axiom Tool | What to check |
|---|------|----------|------------|---------------|
| **J1** | **Service Overlap** | HIGH | `axiom_search({operation="search_contracts", query=<planned_service_name>})` + filter results where `contract_type` is `Class` or `Module` and `file_path` starts with `backend/src/services/` | Planned backend service has an existing contract with a matching name or overlapping `@BRIEF` semantics. Report the candidate `contract_id`, `file_path`, and why the new service would duplicate existing responsibility. |
| **J2** | **Component Overlap** | HIGH | `axiom_search({operation="search_contracts", query=<planned_component_name>})` + filter for `[TYPE Component]` or `file_path` matching `**/*.svelte` | Planned Svelte component has an existing UX contract (check `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY` annotations). Name-based overlap is the first signal; deeper comparison of UX state names confirms functional duplication. |
| **J3** | **Plugin/Module Overlap** | HIGH | `axiom_search({operation="search_contracts", query=<planned_plugin_name>, fuzzy:true})` + filter `file_path` prefix `backend/src/plugins/` | Planned plugin duplicates an existing plugin contract in the plugins directory. Compare `@BRIEF` and `@PURPOSE` to confirm overlap. |
| **J4** | **Neighborhood Collision** | MEDIUM | `axiom_search({operation="hybrid_query", query_mode="semantic_neighborhood", seed_contract_ids=[existing_ids], max_depth:2})` | Planned module falls in the same semantic neighborhood as existing contracts. Neighborhood traversal reveals upstream/downstream dependencies — the new code would create a responsibility overlap with the existing contracts in that neighborhood. |
| **J5** | **Extensible Candidate** | MEDIUM | `axiom_audit({operation="impact_analysis", contract_id=<existing_candidate_id>})` | Existing component has a manageable impact radius (few downstream dependents, isolated relations). Extending it is safer and faster than creating a new component. Report downstream count and related file paths. |
| **J6** | **Code Pattern Match** | LOW | Glob for candidate files first, then `axiom_search({operation="ast_search", file_path=<candidate_file>, pattern=<class_or_function_name>})` per file; OR use `grep -rn '<pattern>' backend/src/ frontend/src/` | Existing code solves the same algorithmic or structural problem. Report file path, line numbers, and relevance assessment. `ast_search` is per-file only — fall back to grep for cross-directory scans. |

### 5. Severity Assignment

Use this heuristic to prioritize findings:

- **CRITICAL**: Violates constitution MUST principle, missing `[C:N]` complexity tag, missing core spec artifact, ADR-rejected path scheduled as work, requirement with zero coverage that blocks baseline functionality
- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion, ADR guardrail drift, ATTN_1 split anchor, ATTN_2 flat ID (C3+), UX state name drift, missing UX triplet on interactive component
- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case, incomplete decision-memory propagation, ATTN_3/ATTN_4 violations, missing UX contract, orphan UX test, missing recovery path, missing Model-first pattern
- **LOW**: Style/wording improvements, minor redundancy, inconsistent annotation formatting

Component Reuse findings:
- **HIGH (J1-J3)**: Planned component has an existing semantic contract with the same name or >80% overlapping `@BRIEF` — strong duplication signal. Recommend reuse or extension instead of new code.
- **MEDIUM (J4-J5)**: Partial overlap or extensible candidate with a manageable impact radius. Recommend impact analysis review before deciding.
- **LOW (J6)**: Code-level similar patterns found via grep or per-file ast_search; may be coincidental or indicate a reusable utility function or micro-component.

### 6. Produce Compact Analysis Report

Output a Markdown report (no file writes) with the following structure:

#### Specification Analysis Report

**Findings Table:**

| ID | Category | Severity | Location(s) | Summary | Recommendation |
|----|----------|----------|-------------|---------|----------------|
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |

**Coverage Summary Table:**

| Requirement Key | Has Task? | Task IDs | Notes |
|-----------------|-----------|----------|-------|

**Decision Memory Summary Table:**

| ADR / Guardrail | Present in Plan | Propagated to Tasks | Rejected Path Protected | Notes |
|-----------------|-----------------|---------------------|-------------------------|-------|

**UX Contract Summary Table:**

| Component | Has @UX_STATE? | Has @UX_FEEDBACK? | Has @UX_RECOVERY? | @UX_TEST Count | Issues |
|-----------|:---:|:---:|:---:|:---:|--------|

**ATTN Rules Compliance Table:**

| Contract ID | C:N | ATTN_1 (anchor) | ATTN_2 (ID) | ATTN_3 (grouping) | ATTN_4 (size) | Issues |
|-------------|-----|:---:|:---:|:---:|:---:|--------|

**Component Reuse Summary Table:**

| Planned Component | Type | Existing Candidate | Location | Overlap Assessment | Recommended Action | Axiom Confidence |
|-------------------|------|--------------------|----------|--------------------|-------------------|:---:|
| `NewExportService` | Service | `ReportsService` | `backend/src/services/reports/` | `@BRIEF` covers similar reporting | EXTEND | HIGH |

- Overlap assessment: cite the `@BRIEF`, `@PURPOSE`, or `@UX_STATE` evidence from the found contract
- Recommended action: `REUSE` (use as-is), `EXTEND` (add to existing), `ADAPT` (copy and customize), or `NEW` (no overlap — truly new)
- Axiom Confidence: `HIGH` (contract match + name match), `MEDIUM` (neighborhood overlap only), `LOW` (AST pattern match only, no contract match)

**Constitution Alignment Issues:** (if any)

**Unmapped Tasks:** (if any)

**Metrics:**
- Total Requirements: N
- Total Tasks: N
- Coverage % (requirements with >=1 task): N%
- Total Contracts in modules.md: N
- UX Contracts with Full Triplet %: N%
- ATTN Rules Compliance %: N%
- Ambiguity Count: N
- Duplication Count: N
- Critical Issues Count: N
- ADR Count: N
- Guardrail Drift Count: N
- Planned Components: N
- Reuse Candidates Found: N
- Reuse Rate (candidates / planned): N%
- HIGH Confidence Reuse Opportunities: N

### 7. Provide Next Actions

At end of report, output a concise Next Actions block:

- If **CRITICAL** issues exist: recommend resolving before `/speckit.implement`
- If only **LOW/MEDIUM**: user may proceed, but provide improvement suggestions
- Provide explicit command suggestions: e.g., "Run `/speckit.specify` with refinement", "Run `/speckit.plan` to adjust architecture", "Manually edit `tasks.md` to add coverage for 'performance-metrics'"
- If **J1-J3 HIGH** reuse candidates exist with HIGH confidence: recommend updating `plan.md` to reference the existing component and adapting `tasks.md` to use extension rather than new creation
- If **J4 extensible** candidates (MEDIUM): suggest exploratory `axiom_audit({operation="impact_analysis"})` on the candidate before deciding to write new code
- If **zero reuse candidates** found but the feature is in a well-established area (dashboard, reports, migration, auth, git): flag that this is unusual — double-check the planned component list manually

### 8. Offer Remediation

Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)

## Analysis Rules

- Treat stale Rust/MCP assumptions in plan/tasks as **real defects** for this Python/Svelte repository.
- Treat missing ADR propagation as a **real defect**, not a documentation nit.
- Prefer repository-real paths (`backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, `frontend/src/lib/**/__tests__/`).
- Do NOT treat `.kilo/plans/*` as feature artifacts.
- **Use `axiom_search` (not grep/file-list) for all codebase lookups in pass J** — axiom understands semantic contracts, not just filenames. `search_contracts` with CamelCase names (`ReportsService`) reliably finds the exact contract; try both CamelCase and snake_case variants.
- Prefer `hybrid_query` with `semantic_neighborhood` over raw keyword search — neighborhood traversal reveals hidden couplings that grep misses.
- Axiom index health is a prerequisite: if `axiom_search({operation="status"})` returns `index_status != "FRESH"`, fall back to `glob` + `grep` on `backend/src/` and `frontend/src/lib/components/` for keyword-based component search, and flag all pass J findings as LOW confidence.
- When `search_contracts` returns empty results for a keyword, try simpler single-word queries and then fall back to `grep -r -l <keyword> backend/src/ frontend/src/lib/components/`.
- `impact_analysis` on a contract with few downstream dependents (< 3) signals a safe extension target; many downstream dependents (> 10) signals a high-risk change.

## Operating Principles

### Context Efficiency

- **Minimal high-signal tokens**: focus on actionable findings, not exhaustive documentation
- **Progressive disclosure**: load artifacts incrementally; don't dump all content into analysis
- **Token-efficient output**: limit findings table to 50 rows; summarize overflow
- **Deterministic results**: rerunning without changes should produce consistent IDs and counts

### Analysis Guidelines

- **NEVER modify files** (this is read-only analysis)
- **NEVER hallucinate missing sections** (if absent from artifacts, report them accurately)
- **Prioritize constitution violations** (these are always CRITICAL)
- **Prioritize ATTN_1/ATTN_2** (split anchors and flat IDs cause downstream model blindness for all implementing agents)
- **Use examples over exhaustive rules** (cite specific instances from artifacts, not generic patterns)
- **Report zero issues gracefully** (emit success report with coverage statistics)
- **Treat missing UX contract annotations as real UX debt** — every untested state is a browser-verification blind spot

## Context

$ARGUMENTS