create-request

Create/Update Request Skill

Trigger

• Keywords: create request, new request, write request, build request, update request, sync progress, scan requests, request status, incomplete requests, request dashboard

Mode Overview

flowchart LR
    A[/create-request] --> B{Mode?}
    B -->|--status| C[Scan: Discover → Parse → Filter → Report]
    B -->|--update-all| F[Batch Update: Scan → Git Verify → Batch Edit → Report]
    B -->|--update| D[Update: Load → Analyze → Map → Update → Report]
    B -->|default| E[Create: Gather → Explore → Generate → Confirm]

Modes

| Mode | Trigger Condition | Action | | -------- | ----------------------------- | ------------------------------- | | create | No file specified / new request | Gather info -> Fill template -> Create file | | update | File specified / update request | Read current state -> Check implementation -> Update progress | | update-all | --update-all flag | Batch scan → git verify → update all stale docs → report | | scan | --status flag | Scan all requests -> Parse metadata -> Filter incomplete -> Report |

Arguments

| Flag | Applies To | Description | |------|-----------|-------------| | --verify-ac | --update (single) | Dispatch Explore agent to verify AC completion with evidence (file:line). Supports auto-detected path via feature context 5-level cascade. Not available with --update-all. |

When NOT to Use

• Feature-level requirements analysis (use /req-analyze — produces 1-requirements.md, a Phase 1 lifecycle doc for problem-space analysis; see Relationship section below)
• Viewing request structure (use request-tracking)
• Writing tech spec (use /tech-spec)
• Code development (use feature-dev)

Relationship with /req-analyze

Request tickets are work breakdown units derived from /tech-spec, not requirements documents themselves. They live in a different document class per @rules/docs-numbering.md.

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

Workflow ordering

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

A request ticket references its parent /tech-spec for technical detail and may optionally link to 1-requirements.md for problem-space rationale (when /req-analyze was run).

Anti-patterns to avoid

| Anti-pattern | Correct approach | |--------------|------------------| | Writing 5-Why / stakeholder analysis inside a request ticket | Put it in 1-requirements.md via /req-analyze; ticket just references it | | Adding ## Progress / ## Status tables to 1-requirements.md | Progress tracking belongs in request tickets, not the lifecycle requirements doc | | Creating one request ticket per whole feature (AC > 8) | Split by layer or functional area; see Granularity Guide in references/template.md | | Treating 1-requirements.md as a prerequisite for creating requests | It is advisory-only; requests work standalone when only tech-spec exists |

Create Mode Workflow

Phase 1: Gather     -> Collect feature, title, priority, requirements
Phase 1.5a: Quick   -> AC count + layer keyword scan (pre-Explore)
Phase 2: Explore    -> Search related code + tech specs
Phase 1.5b: Refined -> Layer mixing (Related Files) + scope breadth + WBS (post-Explore)
Phase 3: Generate   -> Fill template + create file(s)
Phase 4: Confirm    -> Display result + suggest next steps

Phase 1.5: Granularity Check

Assess whether the request should be split into multiple focused tickets. This runs in two passes to balance early detection with accurate analysis.

Signal Detection

| Signal | Detection | Weight | |--------|-----------|--------| | AC count > 8 | Count - [ ] items. Exclude quality-gate ACs matching: /codex-review-fast, /codex-review-doc, /codex-review, /precommit, /precommit-fast, /pr-review | Primary | | Layer mixing | 1.5a: keyword scan for rules/, hooks/, scripts/ in requirements text. 1.5b: classify Related Files into behavior-layer (.md rules/skills) vs code-layer (.sh/.js hooks/scripts) | Primary | | Scope breadth | Requirements has 3+ functionally independent areas | Primary | | WBS groups ≥ 2 | Tech spec has Work Breakdown heading with 2+ independent task groups (secondary, high-confidence only) | Secondary (×0.5) | | Effort > 3 days | Tech spec WBS has multiple M/L items | Secondary (×0.5) |

Decision Logic

signal_count = primary_count + 0.5 × secondary_count

< 2  → proceed as single request (no suggestion)
≥ 2  → suggest split (advisory AskUserQuestion)
≥ 3  → strongly recommend split

Split Suggestion

When triggered, use AskUserQuestion:

## Granularity Assessment

This request has {N} acceptance criteria (target: ≤8) and {layer_info}.

Suggested split:
1. {Title A} — {scope A} ({AC_count_A} AC)
2. {Title B} — {scope B} ({AC_count_B} AC)

Options:
- "Split into {N} requests" (Recommended)
- "Keep as 1 request"

Split by: layer (behavior vs code) if detected, then functional area if scope breadth detected, then balanced AC groups as fallback.

Sibling Request Output

When user accepts split, create indexed files: YYYY-MM-DD-{title-slug}-r1.md, ...-r2.md, etc. (e.g., 2026-03-18-auth-fix-r1.md, 2026-03-18-auth-fix-r2.md). Each gets its own AC subset (target ≤8), scoped Related Files, and conditional > Depends On: header if dependency exists between siblings.

Create Mode: Interaction

If incomplete info, ask:

1. Feature area: Which feature? (e.g., auth, billing, notifications)
2. Title: Brief description
3. Priority: P0 (urgent) / P1 (high) / P2 (medium)
4. Background: Why is this needed?
5. Requirements: What needs to be done? (list)
6. Acceptance criteria: How do we know it's done?

Update Mode Workflow

Path resolution: --update supports three forms:

| Form | Behavior | |------|----------| | --update <path> | Use explicit path (must match docs/features//requests/.md) | | --update (no path) | Auto-detect from feature context (see references/feature-context-resolution.md) | | --update <keyword> | Resolve feature key, then find active request(s) |

Auto-detection logic (when no explicit path):

1. Resolve feature context using 5-level cascade (node scripts/resolve-feature-cli.js)
2. Scan docs/features/<key>/requests/*.md for incomplete requests (Status not in [Completed, Done, Superseded])
3. If exactly 1 active request → auto-select
4. If multiple active requests → AskUserQuestion with numbered list
5. If 0 active requests → offer to create new via create mode
6. If feature not resolved → Gate: Need Human

Phase 1: Load      -> Read existing request document
Phase 2: Analyze   -> Analyze Related Files + git changes
Phase 2.5: Verify  -> (--verify-ac only) Agent-based AC verification
Phase 3: Map       -> Compare implementation with Acceptance Criteria
Phase 4: Update    -> Update Progress / Status / Checkboxes
Phase 5: Report    -> Output change summary