Req Analyze

Requirements Analysis Skill

Trigger

• Keywords: requirements analysis, analyze requirements, decompose requirements, stakeholder analysis, 需求分析, requirement decomposition, analyze needs

When NOT to Use

• Solution comparison / feasibility evaluation (use /feasibility-study)
• Technical specification writing (use /tech-spec)
• Per-task tracking tickets (use /create-request — requests are date-prefixed non-lifecycle docs for progress tracking, not feature-level requirements docs; see Relationship section below)
• Issue root cause analysis (use /issue-analyze)
• Architecture design (use /architecture)
• Implementation (use /feature-dev)

Boundary Contract

/req-analyze is problem-space only:

• Defines problems, analyzes stakeholders, decomposes requirements, prioritizes needs
• Must NOT rank solutions, estimate implementation effort, or produce feasibility recommendations
• Solution-space concerns discovered during analysis → log as Open Questions with suggestion to run /feasibility-study

Relationship with /create-request

1-requirements.md is a lifecycle document, not a task ticket. They live in different document classes per @rules/docs-numbering.md and serve different audiences.

A third artifact sits beside these: intent-<key>.md (ancillary — Design record, written in Phase 5). Its discriminator vs. 1-requirements.md is content class, not audience — it carries constraints only (North star, Non-goals, INV-* invariants, acceptance sketch), no analysis, and both the designer and the implementer read it: the designer skims it in two minutes, the implementer checks work against it before writing code.

Workflow ordering

/req-analyze → /tech-spec → /create-request → /feature-dev
   (Phase 1)    (Phase 2)    (ticket per task)    (implement)

1-requirements.md feeds /tech-spec; /tech-spec then gets broken down into multiple request tickets by /create-request for parallel execution and progress tracking.

Anti-patterns to avoid

Usage

/req-analyze                          # Auto-detect feature, create/update
/req-analyze <feature-keyword>        # Specify feature
/req-analyze --quick                  # Lightweight: FP decomposition only
/req-analyze --deep                   # Full: + /deep-research + debate

Arguments

Workflow

sequenceDiagram
    participant U as User
    participant C as Claude
    participant E as Explore Agent
    participant W as Web Research
    participant DR as /deep-research
    participant CB as /codex-brainstorm

    C->>C: Phase 0: Context Resolution
    C->>C: Phase 1: First-Principles Decomposition
    alt --standard or --deep
        par Phase 2: Research
            C->>E: Code analysis (background)
            C->>W: Web research cascade
        end
        E-->>C: Related modules + patterns
        W-->>C: Domain findings
    end
    alt --deep only
        C->>DR: /deep-research (full domain research)
        DR-->>C: Claim registry + findings
    end
    C->>C: Phase 3: Requirement Structuring
    alt --deep only
        C->>CB: Phase 4: Completeness Challenge
        CB-->>C: Equilibrium conclusion
    end
    C->>C: Phase 5: Write 1-requirements.md
    C->>U: Auto-trigger /codex-review-doc

Phase 0: Context Resolution

Detect the target feature using the 5-level cascade.

See @skills/create-request/references/feature-context-resolution.md for the full algorithm.

node scripts/resolve-feature.js

scan_error gate. scan_error !== false ⇒ the source sets are unknown, not empty — report it and take the ⚠️ Need Human exit rather than analysing requirements against a corpus you could not read, which produces a requirements doc whose "no existing spec" finding is an artefact of the failure. Gate on !== false, not === true: a {} payload from a shell fallback carries no such field at all, and a non-null key is not evidence the sets are complete — scan_error rides alongside a resolved key.

The wrapper, and no || echo '{}': that fallback emits a payload with no scan_error field, which a gate written as scan_error === true — and any consumer that does not inspect the field at all — reads as success. (The role-aware skills gate on scan_error !== false precisely so a missing field counts as failure; the {} fallback is what made the stricter spelling necessary.) It can also be concatenated after the CLI's partial stdout, so JSON.parse throws before any gate runs. resolve-feature.js exits 0 and emits the full shape with scan_error: true for every failure it can observe — a nonzero CLI exit, a signal, a truncated write, a payload that is not the agreed shape. Not for node itself being unavailable: that produces no JSON at all, which is the one case the caller still handles.

Path Validation

When <path> argument is provided:

• Must match docs/features/<slug>/ where slug passes /^[a-z0-9][a-z0-9._-]*$/i
• Reject .. traversal, absolute paths, symlinks outside repo
• Resolve to canonical repo-relative path before use

Scope Gate

For small/clear features (single file change, unambiguous need), ask user whether a full 1-requirements.md is needed or if inline requirements in tech spec §1 suffice. Use AskUserQuestion to confirm.

Advisory-Only Policy

1-requirements.md is advisory, not mandatory. Consistent with docs-numbering.md marking Phase 1 as "Recommended." Downstream skills (/tech-spec, /feasibility-study) work without it but use it as source-of-truth when present.

Budget Tier Auto-Detection

Phase 1: First-Principles Decomposition (all tiers)

1.1 Root Problem (5-Why)

Start with the user's stated need. Ask "Why?" iteratively until the root problem is reached:

1. Surface requirement (what user asks for)
2. Underlying problem (why they need it)
3. Root cause / business driver (what success looks like)