version: "1.0.1" name: create-request description: "Create, update, or scan per-task request tickets for progress tracking. These are date-prefixed non-lifecycle docs under requests/, NOT feature-level requirements (use /req-analyze for those). Use when: tracking task progress, updating completion status, scanning incomplete requests, checking request status dashboard. Not for: feature-level problem-space analysis (use req-analyze for 1-requirements.md lifecycle doc), tech specs (use tech-spec), code implementation (use feature-dev). Output: request ticket with status tracking, referencing parent tech-spec." allowed-tools: Read, Grep, Glob, Write, Bash, AskUserQuestion, Agent

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

Arguments

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.

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

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

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:

Auto-detection logic (when no explicit path):

1. Resolve feature context using the 5-level cascade — node scripts/resolve-feature.js, the

wrapper that owns the failure payload; the CLI behind it is not the entrypoint 1b. `scan_error` gate — scan_error !== false ⇒ the source sets are unknown, not empty. Report it and take the ⚠️ Need Human exit. This is the step that matters most here: an unreadable requests/ directory returns the same empty set as a feature with no tickets, so without the gate step 5 below reads it as "0 active requests" and creates a duplicate ticket beside the one it could not see. Gate on !== false, not === true: a {} payload from a shell fallback carries no such field, so a non-null key is not evidence of completeness

1. Scan docs/features/<key>/requests/*.md for incomplete requests (Status not in [Completed, Done, Superseded, Archived] — the closed set is defined once in scripts/lib/request-status.js; keep this list identical to CLOSED_REQUEST_STATUS)
2. If exactly 1 active request → auto-select
3. If multiple active requests → AskUserQuestion with numbered list
4. If 0 active requests → offer to create new via create mode
5. 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:

Phase 3: Progress Mapping Rules

Phase 4: Auto-Update Items

Phase 4.5: Freeze — a request ticket is a record, not a living document

A request ticket states what was asked for and what happened. That makes it a record: it is appended to while the work runs, and it is never rewritten afterwards to match what the code later became. Doc sync (/update-docs) does not touch it at all — see that skill's Step 1.5.

The closed set is CLOSED_REQUEST_STATUS in scripts/lib/request-status.js — the same list Scan Mode filters on, and the only place it is defined.

Reopening is a decision, not an update: when work resumes on a closed ticket, say so and create a new ticket that references it, rather than editing history so it reads as though it was never finished. The one exception is a factual correction to the record itself — a wrong path, a wrong date — which is a correction, not a re-sync, and is stated as such in the report.

This is what stops the cost this skill's tickets kept paying: a frozen ticket is reviewed under the record-diff profile, whose whole point is that drift from today's code is not a finding (skills/doc-review/SKILL.md § Review Profiles).

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 ∉ CLOSED_REQUEST_STATUS: Completed, Done, Superseded, Archived)
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):

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

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

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.
5. Frozen docs: A doc whose Status is in CLOSED_REQUEST_STATUS is skipped and reported as frozen — Phase 4.5 applies to batch mode identically. Scan Mode already filters these out, so a closed doc reaching Phase 4 means the status was misparsed; report that rather than editing it.

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

Write-Time Budget

A ticket is a work unit, not a narrative. It stays readable only if it is written to a budget and updated by overwriting rather than appending.

Overwrite, do not accumulate. Each update replaces the phase status and its note; it does not add a round. A ticket carrying "Round 1 … Round 7 …" is a review log wearing a ticket's name — that belongs in review-log-<topic>.md, and moving it there costs nothing because the ticket never needed it. This is where request tickets grow without anyone deciding they should.

The budget is a write-time target, not a gate. A ticket already over it is trimmed at the next substantive edit — unless it is closed, in which case it is frozen (Phase 4.5) and left alone.

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

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