ss-tools/.kilo/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, decision-memory continuity, and component reuse analysis.

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