ss-tools/.opencode/command/speckit.analyze.md

description

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, and decision-memory continuity.

User Input

$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, 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 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 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)

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.

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

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

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

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'"

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.

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