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.

| Dimension | /req-analyze → 1-requirements.md | /create-request → requests/YYYY-MM-DD-*.md | |-----------|--------------------------------------|------------------------------------------------| | Doc class | Lifecycle (Phase 1, numeric prefix) | Request ticket (date-prefixed, non-lifecycle — per @rules/docs-numbering.md) | | Count per feature | One (upsert / incremental refine) | Many (one per task) | | Position in workflow | Before /tech-spec (design phase) | After /tech-spec (execution phase) | | Content focus | Problem space — 5-Why, FR/NFR, MoSCoW, stakeholders | Execution — Status, Progress, AC checklist, Related Files | | Granularity | Feature-wide | Single task (AC ≤ 8) | | Update pattern | Document upsert | Status tracking (scan / update / update-all / --verify-ac) | | Audience | Designers, decision-makers | Executors, progress trackers |

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

| Anti-pattern | Correct approach | |--------------|------------------| | Writing 5-Why / stakeholder analysis inside a requests/*.md ticket | Put it in 1-requirements.md; the ticket just references it | | Adding ## Progress / ## Status table to 1-requirements.md | Progress tracking belongs in request tickets; requirements doc is advisory-only | | Creating a 1-requirements.md per task | One per feature; create multiple request tickets instead | | Treating 1-requirements.md as mandatory prerequisite | It is advisory (see next section); downstream skills work without it |

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

| Flag | Description | |------|-------------| | --quick | Lightweight: FP decomposition + stakeholder + structuring only | | --standard | Default: quick + code research + selective web validation | | --deep | Full: standard + /deep-research + Codex completeness challenge | | --feature <key> | Explicit feature key (validated via slug regex) | | <path> | Direct path to feature docs dir (must match docs/features/<slug>/) |

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/tech-spec/references/feature-context-resolution.md for the full algorithm.

node scripts/resolve-feature-cli.js 2>/dev/null || echo '{}'

| State | Mode | |-------|------| | 1-requirements.md exists | Update (incremental — refine requirements based on new input) | | 1-requirements.md absent | Create from template | | Feature not resolved | Gate: Need Human |

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

| Signal | Tier | |--------|------| | User explicit --quick/--deep flag | Always takes precedence | | Single-file change, clear requirements, no ambiguity in Phase 1 | Auto-downgrade to --quick | | Multiple modules affected, some ambiguity, no external dependency | Stay --standard (default) | | Cross-team impact detected in stakeholder scan, external-facing, regulatory constraint | Auto-escalate to --deep |

Phase 1: First-Principles Decomposition (all tiers)

| Step | Action | Output | |------|--------|--------| | 1.1 | 5-Why root problem extraction | Problem Statement section | | 1.2 | Assumptions register | Constraints & Assumptions section | | 1.3 | Mandatory stakeholder scan | Stakeholders table |

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)

1.2 Assumptions Register

For each assumption discovered during 5-Why:

• Document the assumption
• Classify: Technical / Business / Resource / Compatibility
• Note source: user statement / code observation / inferred

1.3 Stakeholder Scan (mandatory at all tiers)

# Grep codebase for affected modules
git diff --name-only HEAD 2>/dev/null
# Search for consumers of the feature area
grep -r "<feature-keyword>" skills/ scripts/ --include="*.md" --include="*.js" -l | head -20

Identify:

• Developers: Who will implement/maintain
• Users: Who invokes the skill/feature
• Operators: Who deploys/monitors
• Dependents: Other skills/modules that consume the output

Output: Stakeholders table with Role + Key Concern.

Phase 2: Research (tier-dependent)

| Tier | Research Scope | |------|---------------| | --quick | Skip (no research) | | --standard | Code analysis + selective web vali