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

Phase 2: Analyze Implementation Progress

# Get changes for Related Files from request document
git log --oneline --since="<created_date>" -- <related_files>

# Check test status
grep -rE "describe|it\(" test/ --include="*<feature>*"

# Check review status
git log --oneline --grep="codex-review" -- <related_files>

Phase 2.5: AC Verification Agent (--verify-ac only)

Dispatched when --verify-ac flag is present on single-request --update. Supports auto-detected path via feature context 5-level cascade. Skipped otherwise (default path unchanged, <10 sec).

Input: AC_LIST from ## Acceptance Criteria (filter quality-gate ACs per codex-code-review Step 1.5 pattern). RELATED_FILES from ## Related Files table.

Agent({
  description: "Verify AC completion for <feature>",
  subagent_type: "Explore",
  prompt: `AC verification specialist.
    AC_LIST: ${AC_LIST}
    RELATED_FILES: ${RELATED_FILES}
    For each AC: read code, verify implementation.
    Output per AC:
    - Status: Complete | Partial | Not Found | Inconclusive
    - Evidence: file:line references
    - Confidence: High | Medium | Low
    - Gap (if Partial): what is missing`
})

Timeout: 60 sec hard limit. Unverified ACs on timeout marked Inconclusive.

Graceful degradation: Agent dispatch fails → warn user, fall back to git-based heuristic (Phase 2 results).

Confidence-to-status mapping:

Condition	Status
All AC Complete with High confidence	Completed
All AC checked but any Medium/Low/Inconclusive	Candidate Complete + verification summary in Progress.Note
Some AC Not Found or Partial	In Progress

Phase 3: Progress Mapping Rules

Implementation Status	Progress Update
Related Files have commits	Development -> In Progress
Test files added/modified	Testing -> In Progress
/codex-review-fast passed	Development -> Done
/precommit passed	Testing -> Done
All Acceptance Criteria checked	Acceptance -> Done

Phase 4: Auto-Update Items

Section	Update Logic
Status	Canonical lifecycle: Pending → In Progress → Candidate Complete → Completed. Candidate Complete = all AC checked but not closure-grade verified (either heuristic-only, or --verify-ac with non-High confidence). Only --verify-ac with all-High confidence sets Completed. Normalize variants: In Development/In Dev → In Progress; Done → Completed
Progress table	Update each phase status based on git changes
Acceptance Criteria	Check checkboxes based on implementation/test results
Progress.Note	Add latest commit message summary

Update Mode: Interaction

If confirmation needed, ask:

1. Confirm target request document path
2. Any manually completed items to check off?
3. Any blocked items to mark?

---

Scan Mode Workflow

Phase 1: Discover  -> Glob docs/features/*/requests/*.md (exclude archived/)
Phase 2: Parse     -> Extract Status, Priority, Created, AC progress from each doc
Phase 3: Filter    -> Keep incomplete (Status ≠ Completed, Done, Superseded)
Phase 4: Report    -> Group by status, sort by priority then date, output markdown

Phase 1: Discovery

Glob: docs/features/*/requests/*.md
Exclude: docs/features/*/requests/archived/*.md

Count total, active, and archived separately.

Phase 2: Metadata Parsing

Support two metadata formats (try in order, use first match):

Format	Status Pattern	Priority Pattern	Created Pattern
Blockquote	> **Status**: <value>	> **Priority**: <value>	> **Created**: <value>
Table	^| Status | **?<value>**? | (anchor to line start, metadata section only — first 15 lines)	^| Priority | <value> |	^| Created | <value> |

Fallback: If metadata missing, extract date from filename (YYYY-MM-DD-*), default status to unknown, priority to --.

AC Progress: Count - [x] (checked) vs total - [ ] + - [x] in ## Acceptance Criteria section.

Feature name: Extract from path — second segment after docs/features/ (e.g., docs/features/auth/requests/... → auth).

Phase 3: Filter & Classify

Status	Classification	Include in Report
Completed	Done	No
Done	Done	No
Superseded	Done	No
In Progress / In Development / In Dev	Active	Yes
Candidate Complete	Active (needs verification)	Yes — group after In Progress
Pending	Backlog	Yes
Design / Proposed	Pre-work	Yes
unknown	Backlog (grouped with Pending)	Yes

Stale detection: Pending requests with Created date > 30 days ago → mark [stale].

Phase 4: Report Format

Console-only markdown output (no file creation). Group by status in actionability order:

1. In Progress — active work, highest actionability
2. Candidate Complete — heuristic-complete, needs --verify-ac confirmation
3. Pending — backlog, includes stale detection
4. Design / Proposed — pre-implementation

Each group as a table with columns: #, Request, Feature, Priority, Created, AC, Path. Pending group adds a Stale column.

Sort order within each group: Priority descending (P0 > P1 > P2 > --), then Created ascending (oldest first).

Bottom summary table: status counts + average age (days since Created).

Summary line at top: N incomplete / M total (K archived excluded).

---

Batch Update Mode (--update-all)

Scan all incomplete requests, cross-reference with git history, and batch-update docs where implementation evidence exists. This automates what would otherwise require running --update on each doc individually.

Phase 1: Discover  -> Reuse Scan Mode Phase 1-3 to find incomplete docs
Phase 2: Verify    -> For each doc, check git log for Related Files commits
Phase 3: Classify  -> Sort into: updatable (has commits) vs unchanged (no commits)
Phase 4: Batch Edit -> Update Status, AC checkboxes, Progress table for each updatable doc
Phase 5: Report    -> Output change summary table

Phase 2: Git Verification

For each incomplete request doc, extract the feature name from path and search for evidence:

Priority: Use Related Files from request doc when available (most accurate). Fall back to feature slug heuristic only when Related Files section is absent.

# Priority 1: Use Related Files from request doc (if present)
# Parse "## Related Files" table → extract file paths → git log per path

# Priority 2: Feature slug heuristic (fallback)
git log --oneline --all -- skills/<feature>/ | head -5

Exclude docs-only commits: Filter out commits that only touch docs/ paths — these are doc-sync commits, not implementation evidence. A valid evidence commit must touch at least one non-docs file.

Phase 3: Classification

Category	Condition	Action
ALL_CHECKED	AC all [x] but Status ≠ Completed/Candidate Complete	Update Status → Candidate Complete (heuristic-only, not Completed)
HAS_COMMITS	Git commits exist for Related Files	Read doc → verify AC → update
LEGACY_METADATA	No blockquote Status (table format or missing)	Check table format; if already Completed → skip
NO_EVIDENCE	No git commits, AC unchecked	Skip (report as unchanged)

Phase 4: Batch Edit Rules

For each updatable doc:

1. Status: If all AC checked (heuristic) → Candidate Complete. If some AC checked → In Progress. Only --verify-ac (single update) can set Completed.
2. AC checkboxes: Cross-reference git diff to determine which ACs are met. Only check ACs with clear implementation evidence.
3. Progress table: Update phase statuses based on commits found.
4. Missing metadata: Add blockquote metadata header if doc only has table format or no metadata.

Phase 5: Report Format

## Batch Update Report

| # | Request | Feature | Before | After | Changes |
|---|---------|---------|--------|-------|---------|
| 1 | Bug-fix redesign | bug-fix-redesign | Pending 0/14 | Candidate Complete 14/14 | Status + AC + Progress |
| 2 | Safe-remove | safe-remove | Pending 0/12 | Candidate Complete 12/12 | Status + AC |
| 3 | Multi-ecosystem | multi-ecosystem | Pending 0/23 | Pending 0/23 | (no changes — no commits) |

**Updated**: N / **Unchanged**: N / **Total scanned**: N

File Naming

Format: YYYY-MM-DD-kebab-case-title.md

Location: docs/features/{feature}/requests/

Output

• Request document at docs/features/<feature>/requests/YYYY-MM-DD-<title>.md
• Sections: Background, Requirements, Scope, Related Files, Acceptance Criteria, Progress, References
• Status: New or Updated

Verification

• File naming follows convention
• All template sections are filled
• Related file links are correct
• Acceptance criteria use checkboxes

After Creation

Request tickets are created after /tech-spec exists (see Relationship section). Suggest execution-oriented next steps:

1. /feature-dev — Start implementation following the ticket's Acceptance Criteria
2. /verify — Run tests after implementation
3. /create-request --update — Sync progress as work completes

Exception: If the ticket was created before a tech spec exists (emergency or exploratory work), consider running /tech-spec first to capture the technical design the ticket will execute against.

References

• references/template.md - Request template + naming convention

Related Skills

Skill	Purpose
request-tracking	Request structure knowledge base
tech-spec	Tech spec writing
feature-dev	Development workflow

Examples

Create Mode

Input: /create-request Feature: Auth Title: Fix validation Priority: P1
Action: Explore related code -> Fill template -> Create file -> Suggest next steps

Input: Create a request document
Action: Ask for required info -> Explore -> Create -> Confirm

Update Mode

Input: /create-request --update docs/features/auth/requests/2026-01-23-fix-login-validation.md
Action: Read request -> Analyze git changes -> Update Progress -> Output summary

Input: Update request progress
Action: Identify request from context -> Analyze implementation -> Auto-update -> Confirm

Input: (after development complete) Sync request document
Action:
  1. Read Related Files
  2. git log to check changes
  3. Update: Development unchecked -> done, Testing unchecked -> in progress
  4. Check completed Acceptance Criteria
  5. Status: Pending -> In Progress