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— produces1-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):
- Resolve feature context using 5-level cascade (
node scripts/resolve-feature-cli.js) - Scan
docs/features/<key>/requests/*.mdfor incomplete requests (Status not in[Completed, Done, Superseded]) - If exactly 1 active request → auto-select
- If multiple active requests → AskUserQuestion with numbered list
- If 0 active requests → offer to create new via create mode
- 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