description: Perform a read-only consistency analysis across spec.md, plan.md, tasks.md, and ADR sources for the active ss-tools feature.
description: Perform a read-only consistency analysis across spec.md, plan.md, tasks.md, contracts/modules.md, and ADR sources for the active ss-tools feature. Covers UX Contract Traceability, ATTN Rules Compliance, and decision-memory continuity.
---
## User Input
@@ -10,62 +10,273 @@ $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, and decision-memory drift across the feature artifacts before implementation proceeds.
Identify inconsistencies, ambiguities, coverage gaps, decision-memory drift, UX contract gaps, and ATTN-rules violations 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 files.
**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 the local constitutional baseline for this workflow. Conflicts with its must-level principles are CRITICAL.
**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. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` and derive absolute paths for `spec.md`, `plan.md`, `tasks.md`, and relevant ADR sources under `docs/adr/`.
- Analyze the active feature directory under `specs/<feature>/` only.
### 1. Initialize Analysis Context
2. Load minimal necessary context from:
-`spec.md`
-`plan.md`
-`tasks.md`
-`contracts/modules.md` when present
-`README.md`
-`.specify/memory/constitution.md`
- relevant `docs/adr/*.md`
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:
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)
- **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)
- 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. |
### 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
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'"
### 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.
/* svelte-markdown renderers use semantic HTML tags — style via cascade */
/* @humanspeak/svelte-markdown renderers use semantic HTML tags — style via cascade */
.markdown-text:global(h1),
.markdown-text:global(h2),
.markdown-text:global(h3){
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
