/req-analyze

name: req-analyze
description: "Requirements analysis — problem decomposition, stakeholder scan, requirement structuring. Produces 1-requirements.md (Phase 1 lifecycle doc, NOT the per-task request ticket — for those use /create-request). Use when: analyzing needs before tech spec, decomposing requirements, stakeholder analysis, 需求分析. Not for: solution comparison (use feasibility-study), tech design (use tech-spec), per-task tracking tickets (use create-request), issue root cause (use issue-analyze)."
allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(node:*), Bash(bash:*), Write, Agent, Skill, AskUserQuestion, WebSearch, WebFetch

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 |

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

| 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 `@skill