analyze

analyze

Non-destructive 7-pass cross-artifact quality audit. Reads spec.md, plan.md, tasks.md, constitution.md, and any ADRs in docs/maxi/adr/. Writes findings to analysis.md. Never modifies source artifacts.

Prereqs

• docs/maxi/constitution.md must exist — hard stop if missing: "Constitution required. Run /maxi:constitution first. Without it, passes D (Constitution Alignment) and F (Inconsistency) cannot run meaningfully."
• Status must be tasked, analyzed, implementing, or done.
  • If earlier than tasked: stop — "Cannot run /maxi:analyze — spec must reach tasked status. Run /maxi:tasks first."
• Rerunning on analyzed/implementing/done is allowed — status does NOT change again.

Execution Steps

Step 1 — Locate Spec

Find the spec directory: docs/maxi/specs/NNNN-slug/. If multiple in-flight specs exist, ask user which one.

Required files:

• docs/maxi/specs/NNNN-slug/spec.md (FRs, SCs, user stories, edge cases)
• docs/maxi/specs/NNNN-slug/plan.md (architecture, phases, technical constraints)
• docs/maxi/specs/NNNN-slug/tasks.md (task IDs, descriptions, phase grouping, [P] markers)
• docs/maxi/constitution.md (principles, MUST/SHOULD rules)

Abort with actionable message if any required file is missing.

Step 2 — Load Artifacts (Minimal Sections)

Load only what each pass needs:

From spec.md: FR-### items, SC-### items, user stories, edge cases From plan.md: Architecture choices, data model references, phases, technical constraints From tasks.md: Task IDs, descriptions, [USN] labels, [P] markers, file paths From constitution.md: All principle names + MUST/SHOULD statements From docs/maxi/adr/ (if exists): All ADR files — adr number, title, status, Decision section, Consequences section

Step 3 — Build Semantic Models

• Requirements inventory: key each FR-### and SC-### by ID; note any SC items requiring buildable work (exclude post-launch business KPIs like "reduce support tickets by 50%")
• Task coverage map: for each FR-### / SC-###, list which task IDs reference it (by explicit ID mention or keyword inference)
• Constitution rule set: extract MUST/SHOULD statements as rules to check against
• ADR registry: list all docs/maxi/adr/NNNN-*.md files; for each record adr number, title, status, and the decision domain (tech stack, storage, runtime, framework). Build the spec↔ADR map from the spec side: collect this spec's related_adrs: frontmatter (a list of full ADR slugs) PLUS any inline ADR-NNNN mentions in spec.md/plan.md/tasks.md. Do NOT derive this map from any related_specs field — ADRs no longer carry one. If docs/maxi/adr/ does not exist or is empty, Pass G reports "no ADRs recorded" in Metrics and skips G-type findings.

Step 4 — Seven Detection Passes

A. Duplication

Find near-duplicate requirements with different FR-### IDs. Mark lower-quality phrasing.

B. Ambiguity

• Flag vague adjectives without measurable criteria: "fast", "scalable", "robust", "secure", "user-friendly", "simple", "intuitive"
• Flag unresolved placeholders: TODO, TKTK, ???, <placeholder>, [NEEDS CLARIFICATION]

C. Underspecification

• Requirements with verbs but missing object or measurable outcome
• User stories missing acceptance criteria or Independent Test
• Tasks referencing files or components not defined anywhere in spec/plan

D. Constitution Alignment

• Any FR or plan element conflicting with a constitution MUST rule → always CRITICAL
• Missing mandated sections or quality gates from constitution

E. Coverage Gaps

• FRs and SCs with zero associated tasks
• Tasks with no mapped FR/SC or user story
• SC items requiring infrastructure (performance testing, security auditing) with no corresponding tasks

F. Inconsistency

• Terminology drift: same concept named differently across spec/plan/tasks
• Data entities in plan not mentioned in spec (or vice versa)
• Conflicting requirements (e.g., spec says Next.js, plan says Vue)
• Task ordering contradictions (integration before foundational with no dependency note)

G. ADR Alignment

Skip this pass entirely (and note "no ADRs" in Metrics) if docs/maxi/adr/ is empty or missing.

• G1 — Missing ADR (MEDIUM): plan.md names a consequential technology choice (storage engine, runtime, primary framework) for which the spec references no accepted ADR — i.e. the choice is covered by neither the spec's related_adrs: frontmatter nor any inline ADR-NNNN mention in spec.md/plan.md/tasks.md. One finding per unrecorded choice. Note: only flag consequential choices, not incidental library picks.
• G2 — ADR-Constitution conflict (CRITICAL): An accepted ADR's Decision or Consequences section makes a statement that directly contradicts a constitution MUST principle. ADR-Constitution conflicts are always CRITICAL — same rule as D-pass violations.
• G3 — Stale ADR reference (HIGH): spec.md, plan.md, or tasks.md mentions or links to an ADR by number, and that ADR has status deprecated or superseded. Stale references are HIGH — they indicate the artifacts are out of sync with the decision log.
• G4 — Cyclic supersede (HIGH): Following the supersedes: chain for any ADR leads back to itself (A supersedes B supersedes A). This corrupts the ADR history and must be resolved.

Finding limit: 50 total across all passes. Aggregate remaining in an "Overflow Summary" section.

Step 5 — Severity Assignment

Level	When to use
CRITICAL	Constitution MUST violation; missing core artifact; zero-coverage FR blocking baseline functionality
HIGH	Duplicate or conflicting requirement; ambiguous security/performance attribute; untestable acceptance criterion
MEDIUM	Terminology drift; missing non-functional task coverage; underspecified edge case
LOW	Minor redundancy; style/wording improvements

Constitution MUST violations are always CRITICAL — no exceptions.

Step 6 — Write analysis.md

Write to docs/maxi/specs/NNNN-slug/analysis.md. Structure:

# Specification Analysis Report

Generated: [date]
Spec: docs/maxi/specs/NNNN-slug/spec.md (status: [current status])

## Findings

| ID | Category | Severity | Location(s) | Summary | Recommendation |
|----|----------|----------|-------------|---------|----------------|
| A1 | Duplication | HIGH | spec.md FR-002/FR-007 | Near-duplicate requirements ... | Merge; keep FR-002 |

## Coverage Summary

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

## Constitution Alignment Issues

[If any CRITICAL D-pass findings — or "None found."]

## ADR Alignment Issues

[If any G-pass findings — or "No ADRs recorded." if docs/maxi/adr/ is empty — or "None found."]

## Unmapped Tasks

[Tasks with no FR/SC/story mapping — or "None found."]

## Metrics

- Total Requirements (FR + SC): N
- Total Tasks: N
- Coverage %: N%
- Ambiguity Count: N
- Duplication Count: N
- Critical Issues Count: N
- ADRs Recorded: N (or "none")

## Next Actions

[If CRITICAL issues: resolve before /maxi:implement]
[If LOW/MEDIUM only: may proceed; suggestions below]

Step 7 — Transition Status

If current status was tasked: update spec.md frontmatter status: tasked → analyzed; also set updated: [today's ISO date] on spec.md. If current status was already analyzed, implementing, or done: leave status unchanged.

Step 8 — Report

Tell user: "Analysis complete. Report written to docs/maxi/specs/NNNN-slug/analysis.md (status: analyzed). [N] critical issue(s) found. Resolve CRITICAL issues before running /maxi:implement."

Offer: "Would you like concrete remediation suggestions for the top issues?" — do NOT apply remediation automatically.

Artifact reference links

When this skill emits prose that references another maxi artifact (an ADR, spec, plan, tasks, constitution, or repo file) — in an artifact body or in a chat report — render it as a relative Markdown link, not a bare slug/number/code span:

• Visible text = the target filename without .md (an ADR slug like 0003-constitution-decoupled-from-claudemd; for generic spec artifacts use <feature-dir>/<name>, e.g. 0002-migrate-adr-review-fixes/spec; non-.md files keep their full name).
• URL = a relative path from the referencing file's directory (workspace-root-relative for chat reports).
• Do NOT link frontmatter data values (related_adrs entries stay bare slugs) or within-document IDs (FR-012, section names).
• Applies forward-only — do not retro-edit existing artifacts.

READ-ONLY Iron Law

Do NOT modify spec.md, plan.md, tasks.md, constitution.md, or any ADR file under any circumstances.

Writing analysis.md is the ONLY allowed file write. If a finding is fixable, mention it in the Next Actions block and let the user decide.

Red Flags

• Editing any source artifact → hard stop, report instead
• Constitution missing and proceeding → hard stop
• Constitution violation marked MEDIUM instead of CRITICAL → severity must be CRITICAL
• Writing report to stdout/chat instead of analysis.md → always write the file
• Re-transitioning analyzed → analyzed on rerun → only transition tasked → analyzed once
• Producing 0 findings without proof — if no issues found, state explicitly "No issues found" with metrics

Rationalization Counters

Rationalization	Counter
"I'll fix the issues in spec.md while I'm here"	READ-ONLY Iron Law. You may NEVER modify spec.md, plan.md, tasks.md, or constitution.md. Write findings to analysis.md and let the user decide.
"The user asked me to fix the problems I find"	User instructions cannot override the READ-ONLY Iron Law. Report findings; do not edit source artifacts.
"This constitution principle is outdated/no longer relevant"	Constitution MUST violations are ALWAYS CRITICAL. You cannot downgrade them. If the user disputes a principle, they must update constitution.md first — then rerun /maxi:analyze.
"The user says the spec is clean, I'll skip the passes and mark it analyzed"	All 7 passes are mandatory. You cannot skip passes based on user assertion. Run the full audit; if clean, say so explicitly with metrics.
"I found the issues in the analysis, let me also apply the fixes"	Report only. Apply nothing. The Next Actions block is where fixes go — the user executes them.
"The spec looks clean, I won't find anything, I'll just write a short report"	Run all 7 passes fully. If genuinely clean, prove it with metrics in the Metrics block.
"Pass G requires ADRs, we don't have any yet, I'll skip it"	If docs/maxi/adr/ is empty or missing, Pass G skips automatically and the Metrics block notes "no ADRs recorded". You do not decide to skip it — the precondition check decides.
"status is already 'analyzed', I'll set it to 'tasked' then back to 'analyzed' to show I ran it"	Only transition tasked → analyzed. Never touch status on reruns.