| 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
| 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 (โค 8 substantive ACs; gate receipts excluded from the budget, never from the lifecycle count) | 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 per ยง Pre-Render AC Count below โ this whole phase runs in Create Mode, where no ticket is rendered yet โ then exclude receipts per ยง Quality-Gate AC Classifier | 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) |
Pre-Render AC Count
Phase 1.5 runs inside the Create Mode workflow, before Phase 3 renders anything, so ยง Live
Checkbox ACs โ which reads a rendered ## Acceptance Criteria section โ has no input here and
would count zero, silently suppressing every split suggestion this phase exists to produce.
One rule, governing every count taken before the ticket exists: the overall {N}, and each
{AC_count_A} / {AC_count_B} in the split suggestion after grouping. Count the criteria gathered
at Phase 1 item 6, one per list item, whatever form the user wrote them in โ numbered, hyphenated
or plain lines. Then exclude receipts per ยง Quality-Gate AC Classifier, applied to those same
strings โ one of that classifier's two permitted uses. The subgroup counts are the same units as the
total, or a split "into two tickets of โค 8" can be proposed out of groups that were never measured
the same way as the number that triggered it.
Live Checkbox ACs
Every path that counts ACs in a ticket that exists โ Scan Mode's AC Progress, the
ยง AC-Form Preflight, Phase 2.5's verification input and decision table, Phase 3's Progress mapping,
Phase 4 and batch mode โ counts the same items, or the same ticket gets two different AC counts
depending on who is looking.
The qualifier is load-bearing: this definition reads a rendered section, so the only counts that
do not come from here are Create Mode's, defined at ยง Pre-Render AC Count.
An AC is a top-level hyphen-form task-list item inside ## Acceptance Criteria that is live document text โ
^ {0,3}-\s+\[(?: |x|X)\] after live-text masking. The indent bound is load-bearing: a deeper
indent under a paragraph is a continuation of that paragraph, so Example only: followed by an
indented - [x] illustrative checkbox is visible prose, not a task list, and an unbounded ^\s*[-*]
counts it as a checked AC. CommonMark also allows * and + bullets and ordered task items; this
repo's template emits hyphens and the corpus contains no other form, so the extractor accepts the
hyphen form only and anything else reaches the ยง AC-Form Preflight's Need Human exit rather than
being promoted. A
checkbox inside a fenced block, an HTML comment, or an indented code example is illustration, not an
acceptance criterion, and a section holding nothing else has no ACs at all โ which is the
ยง AC-Form Preflight's no-mutation exit, not an empty AC set. Some tickets record ACs as an
AC โ evidence table instead; that is a valid form which none of these paths can count, and it
takes the same exit.
Quality-Gate AC Classifier
Scope: display and granularity only. This classifier never touches status derivation. Exactly
two paths use it โ Scan Mode's AC Progress (what the dashboard shows) and Phase 1.5's split signal.
Phase 2.5's decision table, Phase 4's lifecycle and batch mode's Status rule count every AC and
do not consult it.
That boundary is the point. Classifying free-text ACs with a regex is inherently approximate: six
successive refinements each measured clean against the whole corpus, and each was then shown to
admit a behavioural requirement or drop a real receipt. Where a misread only shifts a displayed count it is visible; where it shifts the split suggestion
it may not be, since an undercount can suppress the suggestion silently. Both are advisory and
reversible, which is the property that matters. Where it fed status derivation, a
false positive removed an AC from the set a ticket had to satisfy โ so a ticket could reach
Completed without the work. The fix is not a better regex; it is not letting an approximate signal
decide a durable record.
One consequence, and it is the correct one: an unchecked Pass /precommit keeps a ticket at
In Progress until that gate actually runs. A ticket whose gates have not run is not finished.
An AC is a quality gate only when it is a receipt โ its content is that a gate ran, or why it
has not. Neither containing a gate command nor merely opening with one is the test:
`/precommit` โ Try script -> fallback + graceful skip opens with a gate command and is an
implementation requirement for /precommit. A receipt is a gate command plus one of:
| Receipt marker | Example |
|---|
a receipt word โ Pass / Passed / passes / ้้ | Pass /codex-review-doc |
a round N citation | `/codex-review-fast` round 1 |
a named verdict sentinel after a dash โ exactly these six pairs: โ
PASS / โ
Ready / โ
Mergeable / โ Blocked / โ Needs revision / โ FAIL | `/precommit` โ โ
PASS |
a gate lifecycle tail โ superseded or pending followed within a bounded window by a round N or verdict reference, or tracked below | โ pending Codex round 30 verdict |
A bare marker must also end the receipt โ the intended semantics, subject to ยง Known residuals
below, which names the forms the published regex still accepts against this rule. pass, round N and tracked below are ordinary
English too, so each must be followed by end-of-AC, a parenthetical, or a paired verdict sentinel โ
otherwise /precommit passes selected flags through to the underlying runner, round 3 results must be persisted and failure details are tracked below the originating step all read as
receipts. A receipt is short; a requirement continues into a sentence.
superseded and pending need that bounded follow-on precisely because they are ordinary English:
`/precommit` โ pending jobs must resume after the build finishes is a behavioural requirement,
and dropping it from the displayed count understates what is left. (Under the old design, where
this classifier fed status derivation, the same misread could let a ticket advance without the AC.
That is why it no longer does โ the consequence is now a wrong number on a dashboard or a
misfired split suggestion.) Labels are optional and may be bold or plain (AC-8:, **AC-Q1**).
^(?:(?:\*\*[^*]{1,24}\*\*|[A-Za-z][\w.-]{0,12})\s*[:๏ผ]?\s+)?(?:(?:pass(?:ed|es)?|้้)\s+`?/(?:codex-review-fast|codex-review-doc|codex-review|precommit-fast|precommit|pr-review)\b|`?/(?:codex-review-fast|codex-review-doc|codex-review|precommit-fast|precommit|pr-review)`?(?:[^โ(๏ผ:๏ผ]{0,40}?(?:\bpass(?:ed|es)?\b|้้|\bround\s+\d+\b)(?=\s*$|\s*[๏ผ(]|\s*[,๏ผโโ]\s*[โ
โโ])|[^โ(๏ผ:๏ผ]{0,60}?\s*[โโ]\s*(?:round\s+\d+|(?:superseded|pending)[^โ]{0,30}?(?:round\s+\d+|verdict)|[^โ]{0,40}?\btracked below\b(?=\s*$|\s*[๏ผ(]|\s*[,๏ผโโ]\s*[โ
โโ])|(?:โ
\s*(?:PASS|Ready|Mergeable)|โ\s*(?:Blocked|Needs revision)|โ\s*FAIL))))
Case-insensitive (/i) โ `/codex-review-doc` pass is as much a receipt as Pass /codex-review-doc.
Three ways to be a receipt: a receipt word then a gate command; a gate command followed closely by
one; or a gate command whose line ends in an explicit verdict tail after a dash โ โ round 3,
โ โ
PASS, โ โ Blocked. That third branch is why a separator is not an unconditional boundary:
`/codex-review-fast` re-review after the round-2 fixes โ round 3, โ Blocked is a receipt whose
decisive token sits past the dash. What the tail must not be is prose โ `/precommit` โ Try script -> fallback has a dash and is an implementation requirement, and a bare โ
is not enough
either (โ โ
ๅทฒ้ฉ่ญ stays substantive). Only a named verdict sentinel counts, and only as one of the six pairs above โ the mark and the
word are matched together, not as a cross-product, so โ
FAIL, โ Ready and โ PASS are not
receipts. A contradictory sentinel is malformed text, and reading it as a receipt would hide a real AC from
the displayed count โ or a gate lifecycle tail in the bounded form the table
above requires, because an unchecked gate AC recording why its gate has not run yet is still
bookkeeping, not work. Two real ones live in
docs/features/auto-loop-evolution/requests/2026-08-08-receipt-integrity-issues-9-10-11.md.
The bounded window still stops at ( and ๏ผ, so a gate AC whose tail sits past a parenthetical
stays counted as work. Two real ones do:
docs/features/auto-loop-evolution/requests/2026-08-08-receipt-integrity-issues-9-10-11.md lines 860
and 878, `/precommit` then `/codex-review-doc` โฆ (task #85) โ pending โฆ. These are known,
intentional exceptions, not oversights: widening past parentheses is where behavioural ACs live,
and the failure direction here overstates the displayed remainder rather than understating it. It
does not hold the lifecycle open โ under the all-AC rule an unchecked receipt does that on its own.
Revisit only with a corpus measurement showing the widened form adds no false positive.
| Excluded โ a receipt that a gate ran | Kept โ the command is the subject of real work |
|---|
Pass /codex-review-doc๏ผโ
Mergeable๏ผ | `/precommit` โ Try script -> fallback + graceful skip |
Pass `/codex-review-fast` โ `/precommit` | `/pr-review` ๆดๅ๏ผ่ชๅๅผๅซ fast mode |
`/codex-review-doc` ้้ | โฆStop ๅๅ ฑ็ไบๅฏฆโฆไธไธๅซ `/codex-review-fast` |
AC-8: Pass /codex-review-doc โฆ โ
Verified | โฆๆฐๅข 10 ๅๆธฌ่ฉฆ๏ผโฆ`/precommit` ่ทฏ็ฑโฆ๏ผ |
`/codex-review-fast` round 1 โ โ Blocked | Skill routing๏ผๆฏๆด่ณๅฐ 8 ๅ route target๏ผโฆ๏ผ |
`/codex-review-doc` pass | `/precommit` runner ๆฏๆด ecosystem ๅตๆธฌ โ โ
ๅทฒ้ฉ่ญ |
`/precommit` โ โ
PASS (comment_blocks, lint:fix, build, test) | ๆไพ copy-pasteable ไฟฎๆญฃๆไปค๏ผๅฆ โฆ๏ผ |
Every row is a real AC from this repo's requests/, and both columns are pinned by
test/skills/create-request-scan.test.js. The right column is what a position-only rule got wrong:
it dropped implementation work from the displayed count, so the dashboard understated what was left. The left column's last two rows are what a bold-label-only rule got wrong in
the other direction โ a real receipt counted as work overstates the displayed remainder. It does
not hold the lifecycle open: by the all-AC rule an unchecked receipt keeps a ticket open on its own,
whatever this classifier says about it.
Known residuals. The published regex is looser than the prose above in places: forms like
Pass /precommit must preserve selected flags and `/precommit` โ round 3 results must be persisted still match, because the terminator rule reaches the bare post-command markers but
not every route. These are accepted approximation residuals, not open defects. Chasing them
produced six refinements, each corpus-clean and each then shown to admit prose or drop a receipt;
the seventh attempt dropped 26 real receipts. Bounding the classifier to display and granularity
is what makes residuals affordable. The cost is a slightly wrong number on a dashboard, or an
advisory split signal that fires when it need not (false negative) or stays silent when it should
fire (false positive); the route that made them dangerous is closed. Tighten one only with a corpus measurement showing it
adds no false negative.
The classifier fails toward substantive โ when an AC is genuinely ambiguous, keep it. Since the
classifier no longer feeds status, the cost of either error is a display figure or an advisory
split signal rather than a lifecycle decision; keeping an ambiguous AC still makes the count honest about what a reader can
verify.
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} substantive acceptance criteria (target: โค8, gate receipts excluded) 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 substantive, counted per ยง Pre-Render AC Count), 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 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
- 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)
- 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 0: Freeze -> Reparse Status. Closed (`CLOSED_REQUEST_STATUS`) -> no ordinary update: report frozen, exit.
One path continues: an explicitly authorized factual correction (Phase 4.5), which performs
that correction and nothing else, recorded in `Progress.Note`
Phase 1: Load -> Read existing request document
Phase 2: Analyze -> Analyze Related Files + git changes
Phase 2.4: Preflight -> ยง AC-Form Preflight (all modes, unconditional)
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>
AC-Form Preflight (all modes, unconditional)
This runs in every update mode โ --update with or without --verify-ac, and --update-all
(its step 2). It is defined here, outside the verify-only phase, because that phase declares itself
"skipped otherwise": a reader following the mode instructions would otherwise skip the only
definition of the check and reach mutation logic with an unparsed AC set.
Order: Phase 0 freeze check โ this preflight โ any status, Progress-table or checkbox mutation.
That is the whole of what it gates, and the narrowness is deliberate. An authorized factual
correction โ Phase 4.5's exception: a wrong path, a wrong date, an unfilled template placeholder โ
runs after Phase 0 and does not pass through this preflight, because it derives nothing from the
AC set and asks nothing of it. Gating it here would revoke the one edit Phase 4.5 and
/update-docs ยง Step 1.5 both keep reachable, and revoke it exactly where it is needed most: a
ticket recording its ACs as an evidence table has no parsed checkboxes, so it would become the one
ticket whose wrong path can never be corrected. Such a correction changes the authorized fact and
Progress.Note only, and says so in the report.
Read the ticket's ACs per ยง Live Checkbox ACs. If there is no readable live checkbox AC set โ
no ## Acceptance Criteria section at all
(docs/features/auto-loop-evolution/requests/2026-08-04-degraded-writer-lost-update.md is a real
one); the section present but containing no checkbox items; ACs recorded as an evidence table
(docs/features/scope-discipline/requests/2026-08-15-scope-discipline-implementation.md); or any
other form this procedure cannot parse โ or the section contains a checkbox-like item outside that
grammar at all (* [ ], + [ ], 1. [ ], an item indented past three spaces), or mixes task-list
items with an evidence table โ then no status mutation: report it and take the
โ ๏ธ Need Human exit. Never call an unparsed AC set empty, and never derive a status from one โ
"every AC is checked" is vacuously true of nothing, and that is how a ticket with no
ACs at all would be promoted.
A non-empty parse is not a complete one, which is why the unsupported-form clause is not
redundant with the empty-set clause. A section holding - [x] done beside * [ ] not done parses
to one item, all of them checked โ the unchecked AC written in an unsupported marker does not fail
the check, it disappears, and the ticket promotes with outstanding work. Mixed representation is
refused for the same reason: whichever form this procedure cannot read is the form whose state stops
being counted. Refuse the section as a whole; never parse the part that happens to be readable.
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 is the complete live checkbox AC set the ยง AC-Form Preflight parsed (ยง Live Checkbox ACs) โ not filtered by ยง Quality-Gate AC Classifier. Filtering it here was the last status-path leak: gate ACs dropped out of the report, so the report could not carry one result per AC and the table read it as unaccounted โ the classifier reaching status through report validity after being told it never decides status. 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.
A ticket is a RECORD of work done at a point in time, not a description of today's code:
a Related File missing from the working tree is NOT evidence the AC was never met.
For every absent path, consult git history before concluding:
git log --diff-filter=D --oneline -- <path> # which commit deleted it
git show <deletion-commit>^:<path> | grep -n '<pattern>' # NOTE the ^ โ the path does
# not exist AT the deletion commit; `git show <deletion-commit>:<path>` exits 128.
# For a merge commit pick the parent explicitly (^1 / ^2).
git log -S '<distinctive string>' --oneline -- <path> # find the introducing commit
Output per AC:
- Status: Complete | Complete (later removed) | Partial | Not Found | Inconclusive
- Evidence: file:line references (historical evidence as commit:file:line)
- 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 the user and fall back to the git-based
heuristic (Phase 2 results). A failed dispatch is not a verification result โ it means
--verify-ac did not run. So the run continues as ordinary --update: the decision table below
is skipped entirely, checkboxes come from implementation evidence exactly as they do without the
flag, and the ceiling is Candidate Complete (only a completed verification can set Completed).
Reading a failed dispatch as an "empty report" instead would send it into the invalid-report rules,
where Phase 4 forbids touching any checkbox โ and the heuristic's whole job is to set them. Two
directives, two different outcomes for the same input; this sentence is which one wins.
A deleted subject is not an unmet AC. Verification runs against the tree as it is now, but the
ticket records the tree as it was. When a later change removes what an AC was about โ this repo's
hook-lightweighting deleted hooks/post-tool-review-state.sh and hooks/session-init.sh in
0b3b8f5, and three test/hooks/*.test.js suites in 91b5fc9 (both 2026-08-13), all of them
named as Related Files by older P0 tickets โ a naive run
returns Not Found for every one of them and the mapping above would push a finished ticket back
to In Progress. That is not a status update; it is falsifying the record, and it points the
reader at work that does not exist. Resolve such an AC through git history and record it as
Complete (later removed), naming the removing commit. If history cannot settle it, the AC is
Inconclusive โ never Not Found, and never a downgrade.
Write that finding into Progress.Note, never into a new top-level metadata field. Phase 4.5
and skills/update-docs/SKILL.md ยง Step 1.5 agree that --update's mutable set is exactly four
fields โ Status, the Progress table, AC checkboxes, Progress.Note โ and adding a Note: or
Verification: line to the ticket's metadata blockquote edits the record itself. A verification
result is commentary on the work, so it belongs in the Progress table beside the phase it concerns.
Confidence-to-status mapping:
Ordered โ the first matching rule wins. The rules are a decision procedure, not independent
tests: Inconclusive is a verdict while High / Medium / Low are confidence, so one AC
carries both and would match several independent descriptions at once.
In an accounted report, decisive verdicts drive the status directly; the boxes are consulted
only when the report yields no usable lifecycle conclusion โ an invalid or unaccounted report โ or
for Inconclusive. The accounting qualifier is not
decoration: an unaccounted report can still be full of decisive-looking verdicts โ v3.0.12 records
seven Complete/High results for a nine-AC ticket โ and rules 1โ2 must ignore every one of them.
For Complete, Complete (later removed), Partial and Not Found in an accounted report the
report carries a
verdict and a confidence per AC, and Phase 4 updates the boxes from that same evidence, so reading
both would only invite them to disagree. Two earlier versions of this table read checkbox state for
those verdicts as well, and each needed a verdictโcheckbox transition matrix before it was
deterministic: an AC reported Complete at Medium matched different rules depending on an
unwritten rule about what the checkbox became. Confining the boxes to the cases below removes that
question rather than answering it.
The boxes speak in two situations, and only two. The invalid-report rules, where the report
yields no usable lifecycle conclusion โ and note the distinction: an unaccounted report is not an
empty one. It can carry real, valid findings (the two demoted tickets in this repo record 3-of-5 and
7-of-9 verified ACs), and those findings belong in Progress.Note. What it cannot do is settle the
lifecycle, because a conclusion drawn from a partial account is not a conclusion about the whole.
So the boxes decide the status and the partial evidence is kept rather than discarded. And
Inconclusive, which is the one verdict carrying no completion information โ "nothing was
learned" is not evidence of done or not-done, so the preserved box is again the only thing that
speaks. An Inconclusive result on an unchecked AC therefore reopens the ticket, while the same
result on a checked one does not: collapsing those two into one status would advance unresolved
work to Candidate Complete while Phase 4 leaves its box unchecked โ a ticket simultaneously
Candidate Complete and, by that status's own definition, not eligible for it.
The AC set is every live checkbox AC the ticket has (ยง Live Checkbox ACs) โ all of them,
gate receipts included. This table does not consult ยง Quality-Gate AC Classifier: that classifier is
an approximate reading of free text, and letting it decide status meant one misread could drop an AC
from the set a ticket had to satisfy.
The set is accounted for when the report carries exactly one result per AC, in order, each with
a verdict from {Complete, Complete (later removed), Partial, Not Found, Inconclusive} and a
confidence from {High, Medium, Low}. A missing, duplicated, extra or malformed row means it is
not.
| # | Stage | Condition | Status |
|---|
| 1 | report validity | The report is empty, unparseable or unaccounted for, and any AC is unchecked | In Progress. The report settles nothing about the whole, so the ticket's own record stands, and it says the work is unfinished. Any partial findings it did carry go in Progress.Note |
| 2 | report validity | The report is empty, unparseable or unaccounted for, and every AC is checked | Candidate Complete, stating in Progress.Note that verification did not conclude |
| 3 | verdicts | Any AC Partial or Not Found | In Progress |
| 4 | verdicts | Any AC Inconclusive on an unchecked AC | In Progress. Nothing was learned, so the preserved box is the only evidence and it says the work is unfinished |
| 5 | verdicts | Any remaining Inconclusive (on an already-checked AC), or any confidence below High | Candidate Complete + verification summary in Progress.Note |
| 6 | verdicts | Every AC is Complete or Complete (later removed) at High | Completed. Record every removal commit in Progress.Note (the Acceptance row's Note cell) โ one AC or twelve |
The table's domain begins after a successful ยง AC-Form Preflight. An unreadable AC set exits
there and never reaches here, which is why no row covers it โ a row that did would be dead.
Rules 1โ6 exhaust the declared input space, so there is no catch-all row: rules 1โ2 take every
invalid or unaccounted report, and rules 3โ6 take every combination of the five verdicts and three
confidence values that an accounted report can carry. A row labelled "anything else" sat here until
two independent reviews enumerated the space and found nothing that reached it โ a fallback nothing
can reach is not safety, it is a false impression of it. If a future verdict or confidence value is
added, add its row rather than relying on a fallback.
Rule 6 is the only rule that yields Completed. It never sees a report that did not conclude,
because rules 1โ2 have already taken those. There is no empty-set rule any more: the ยง AC-Form
Preflight already exits on a ticket with no readable ACs, and now that gate receipts are counted,
classification can no longer empty the set.
Every row names exactly one outcome โ a row offering two would put the choice back where this table
exists to remove it.
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 |
| Every AC checked (ยง Live Checkbox ACs โ all of them) | Acceptance -> Done |
Phase 4: Auto-Update Items
Phase 0 and the ยง AC-Form Preflight must both have passed. --update reparses the Status before anything else and stops on a
closed ticket, exactly as batch mode's step 1 does โ the ordering is a step in the declared
workflow, not a clause inside a table row, because a reader following the phases in order would
otherwise reach these mutations before Phase 4.5 tells them the record is frozen. The only path
that edits a closed ticket is the separately authorized factual correction Phase 4.5 defines.
| Section | Update Logic |
|---|
Status | Canonical lifecycle: Pending โ In Progress โ Candidate Complete โ Completed. The Candidate Complete invariant is stated below this table, once. Under --verify-ac the status is whatever Phase 2.5's decision table yields; do not maintain a second mapping here. That table reaches Candidate Complete by more routes than a summary keeps up with โ an unaccounted report with every AC checked, a remaining Inconclusive on an already-checked AC even at High, and any confidence below High โ which is why this row delegates instead of enumerating. Only that table's closing rule sets Completed. Normalize variants at creation or manual authoring only: In Development/In Dev โ In Progress; Done โ Completed. --update must not normalize Done: it is a member of CLOSED_REQUEST_STATUS (Phase 4.5), so a ticket carrying it is frozen and an update may change nothing on it โ rewriting it to Completed is an edit to a closed record, not a normalization. The freeze check runs before every Phase 4 mutation in single-update mode exactly as it does at batch step 1 |
Progress table | Update each phase status based on git changes |
Acceptance Criteria | Under --verify-ac, the transition is per verdict and independent of confidence: Complete and Complete (later removed) โ checked; Partial and Not Found โ unchecked; Inconclusive โ leave the box as it was (nothing was learned); an invalid or unaccounted report โ change nothing. Without --verify-ac, check boxes from implementation/test evidence as before. This decides the boxes only. Phase 2.5's status table is driven by the report, with two documented fallbacks to the boxes โ the invalid-report rules, and Inconclusive, which carries no completion information โ so the two cannot disagree |
|
The Candidate Complete invariant. Candidate Complete means every AC is checked โ all of them,
with no exception for gate receipts โ and closure-grade verification has not concluded. ยง Quality-Gate
AC Classifier is display-only and is not consulted.
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.
| Status | What --update may change |
|---|
Any status not in CLOSED_REQUEST_STATUS โ isOpenRequestStatus() is the negation, so this covers Pending, In Progress, Candidate Complete, the variants Phase 4 normalizes (In Development, In Dev), Design, Proposed, and a Status that failed to parse | Status, Progress table, AC checkboxes, Progress.Note โ the fields above. Naming only the three canonical values here would leave every other open status admitted by Phase 0 with no mutable set at all, which reads as frozen and is the opposite of what the parser says |
Any member of CLOSED_REQUEST_STATUS โ currently Completed, Done, Superseded, Archived | Nothing. A closed ticket is frozen |
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, or an unfilled template placeholder: text that was never a statement about this ticket at
all, such as a trailing **Status**: Pending / In Progress / โฆ legend the author never replaced.
The exception authorizes only that correction, and its eligible targets are closed: a
non-lifecycle recorded fact (a path, a date, a reference), or the removal of an unfilled
placeholder. It must never change Status, a Progress phase status, or AC checkbox state โ
those are the lifecycle fields, and they stay governed by the freeze, the AC-form preflight and the
ordinary transition rules whatever else is being corrected. Without that exclusion the exemption
swallows the rule it follows: a wrong Status on a closed ticket is a "fact" in ordinary language,
so an agent could relabel a lifecycle edit as a correction and walk straight past the preflight.
Unrelated tidying is not authorized either โ the correction is the named fact and nothing beside
it.
Removing one is not cleanup of record content, because it never was record content; leaving it is
worse than removing it, since a second Status field that parseRequestStatus() does not read and
no later update maintains will drift into contradicting the real one. Correcting it in place โ
writing today's status into it โ is the one thing not allowed: that manufactures the duplicate
rather than removing it. State the removal in Progress.Note as with any other correction โ 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
Status is parsed by parseRequestStatus() in scripts/lib/request-status.js โ that module is the
contract; the Status column below only restates it. It recognises three conventions, and it is
what skills/next-step/scripts/analyze.js and scripts/lib/fc-extractor.js already call. A
hand-rolled scan implementing only some of them reports real tickets as unknown โ a
## Status: Completed ticket read as unknown lands in the report as open work, which is the
opposite of what it says. Priority and Created have no such module: parse them per this table.
| Format | Status Pattern | Priority Pattern | Created Pattern |
|---|
| Blockquote | > **Status**: <value> | > **Priority**: <value> | > **Created**: <value> |
| Heading | ^#{1,6}\s*Status\s*:\s*<value> โ e.g. ## Status: Completed | โ | โ |
| Table | /^|\s*status\s*|([^|\n]+)|/im โ the parser's actual expression: a negated class for the cell (three competing quantifiers over one run measured cubic, ~20s on a malformed row), case-insensitive on the word status only. Bold is stripped from the extracted, trimmed cell afterwards, never by a second whole-line pattern | ^| Priority | <value> | | ^| Created | <value> | |
Order is blockquote โ heading โ table, first match wins. The scan window is the first
30 lines (HEAD_LINES in that module), measured against this repo's corpus โ not 15.
Fallback: If metadata missing, extract date from filename (YYYY-MM-DD-*), default status to
unknown, priority to --. unknown classifies as open in Phase 3, matching
isOpenRequestStatus(): an unlabelled ticket is unfinished work, never finished work.
AC Progress: Derive the checked and total counts per ยง Live Checkbox ACs โ that section owns
the item syntax (including [X]) and the live-text rule; restating either here is how they drifted โ
then report the count excluding gate receipts, per ยง Quality-Gate AC Classifier. Note gate ACs
separately if at all.
This is one of the classifier's two permitted uses, and it is why it exists: on this repo there are
open tickets whose only unchecked ACs are gate receipts. Without this exclusion their raw checkbox
ratio would read as incomplete even though every substantive AC is done โ which is the misreading
the exclusion prevents, not one it leaves behind. Said the other way round: after the exclusion
those tickets display a complete substantive ratio, and the deficit exists only in the pre-filter
count.
(No corpus count is quoted: the number depends on the exact measurement procedure, and the
rationale does not need it.)
This is a display figure, not the lifecycle. Status is derived from every AC (Phase 2.5,
Phase 4, batch mode), so a ticket showing 6/6 here can still be In Progress because a gate has
not run. That is not an inconsistency โ the dashboard answers "how much of the work is left" and the
status answers "is this ticket finished", and an un-run gate means it is not.
Report AC progress as โ, never as 0/0 and never as a finding, for every unreadable AC form
ยง Live Checkbox ACs names: an evidence table
(docs/features/scope-discipline/requests/2026-08-15-scope-discipline-implementation.md), a ticket
with no ## Acceptance Criteria section
(docs/features/auto-loop-evolution/requests/2026-08-04-degraded-writer-lost-update.md), a section
holding no live checkbox items, or an unsupported syntax. Scan Mode is display-only, so it does
not take the preflight's Need Human exit โ but rendering any of these as 0/0 would publish "this
ticket has no ACs" when the truth is "this procedure cannot read them".
Feature name: Extract from path โ the segment immediately after docs/features/, i.e. the third path segment (e.g., docs/features/auth/requests/... โ auth; two segments after the prefix is requests, the same for every ticket).
Phase 3: Filter & Classify
| Status | Classification | Include in Report |
|---|
| Completed | Done | No |
| Done | Done | No |
| Superseded | Done | No |
| Archived | 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:
- In Progress โ active work, highest actionability
- Candidate Complete โ all ACs checked, not closure-grade verified (heuristic-only, or a
--verify-ac run that did not conclude); needs a closure-grade --verify-ac
- Pending โ backlog, includes stale detection
- 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 -5 --oneline --all -- skills/<feature>/
Read git's own exit status, and do not pipe it away. git log โฆ | head -5 reports the status of
head, which is 0 even when git exited 128 โ so a non-repository, an unreadable object store and a
genuine "no commits" all look identical, and the tri-state below collapses to NO_COMMITS exactly
where it must not. Use -5 on git itself. Status 0 with output โ HAS_COMMITS; status 0 with no
output โ NO_COMMITS; any non-zero status โ EVIDENCE_UNKNOWN. A shallow clone is the same
class: it can answer "nothing found" without having the history to know, so treat a repository
reporting --is-shallow-repository as true as EVIDENCE_UNKNOWN rather than as an answer.
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.
Report one of three results per document, never a bare boolean: HAS_COMMITS, NO_COMMITS, or
EVIDENCE_UNKNOWN when the probe did not conclude (nonzero git log, unreadable repository,
missing history). Phase 3 row 4 is only sound over NO_COMMITS; EVIDENCE_UNKNOWN takes the
โ ๏ธ Need Human exit before classification.
Phase 3: Classification
Classification queues an action; nothing here edits a document. Every Action below is a
proposal that Phase 4 executes only after its freeze and AC-form preflights pass โ which is what
makes those preflights a guarantee rather than a convention.
Ordered first-match: a doc takes the action of the first row it satisfies and no other. The
rows overlap by construction โ a Pending ticket with unchecked ACs and no commits satisfies more
than one โ so an unordered reading queues two contradictory actions for one document. How the
Status is written (blockquote, heading, table, or absent) is deliberately not a category here:
representation decides the shape of the edit, never whether to edit, and it is settled in Phase 4
step 6.
| # | Category | Condition | Action |
|---|
| 1 | FROZEN | Status โ CLOSED_REQUEST_STATUS per parseRequestStatus() | Skip, report as frozen. First because a closed ticket must never be reached by a later row |
| 2 | ALL_CHECKED | Checkbox ACs parsed successfully (not an evidence-table ticket โ see the AC-form preflight) and every AC is checked per ยง Live Checkbox ACs (all of them) but Status โ Completed/Candidate Complete | Update Status โ Candidate Complete (heuristic-only, not Completed) |
| 3 | HAS_COMMITS | Git commits exist for Related Files | Read doc โ verify AC โ update |
| 4 | OTHERWISE | No earlier row matched, and Phase 2 returned NO_COMMITS | Skip, report as unchanged, naming the reason where it is an unreadable AC set |
Phase 2 returns one of three results, and row 4 depends on which: HAS_COMMITS, NO_COMMITS, or
EVIDENCE_UNKNOWN โ a git log that exited nonzero, an unreadable repository, any probe that
did not conclude. EVIDENCE_UNKNOWN never reaches classification at all: report it and take the
โ ๏ธ Need Human exit, exactly as the scan_error gate does for an unreadable requests/ directory
and for the same reason. Unknown evidence is not absent evidence, and the whole of row 4 rests on
that difference: "no earlier row matched" entails "no qualifying commits" only when the probe
actually answered. Read the other way, a repository that could not be searched would be reported as
a document with nothing to do.
Row 4 is the residual, deliberately: every document Scan Mode returns must match some row, and a document that matches no row has no defined action โ the same defect as two contradictory ones.
A Status that parseRequestStatus() resolved from the heading or table form is not a
category and not "missing metadata" โ Phase 2 lists all three forms as canonical, and this repo has
real ## Status: Completed tickets. It classifies by its value like any other, and row 1 catches it
when that value is closed. A parseRequestStatus() of null is open by isOpenRequestStatus() and
classifies on evidence. Both are then edited per Phase 4 step 6, which owns the form question.
Phase 4: Batch Edit Rules
For each updatable doc:
- Frozen docs (preflight โ before any mutation): 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 โ a stale scan or a misclassification. That is exactly why the check must run first: reparse the Status here and stop, rather than editing a historical record through steps that would otherwise have already run.
- AC form (preflight โ before any status or checkbox edit): Apply ยง AC-Form Preflight (all modes, unconditional). A ticket recording its ACs as an evidence table has no parsed checkboxes, and "zero parsed checkboxes" must never read as "all checked" โ that is how a table-form ticket would be set to
Candidate Complete vacuously. Report it and leave it unmutated, exactly as single-request mode does.
- AC checkboxes: Cross-reference git diff to determine which ACs are met. Only check ACs with clear implementation evidence. This runs before the Status step, not after it. Status is derived from the checkboxes, so deriving it first reads the pre-update state: a
Pending 0/14 ticket whose commits satisfy every AC would be written In Progress and then have all fourteen boxes checked, leaving In Progress 14/14 โ and making this section's own Pending 0/14 โ Candidate Complete 14/14 example unreachable.
- Status: Count every AC per ยง Live Checkbox ACs โ the gate classifier is display-only and is not consulted here, so an unchecked
Pass /precommit does hold the ticket open, which is what an un-run gate means. If all ACs are checked (heuristic) โ Candidate Complete. If only some are โ In Progress. Only --verify-ac (single update) can set Completed.
- Progress table: Update phase statuses based on commits found.
- Missing metadata: Table format is a valid canonical format (Phase 2,
parseRequestStatus()), so a
table-format ticket is not missing metadata โ never add a blockquote header beside it. Blockquote outranks
table in the parser's precedence, so doing that silently changes the value every consumer reads. Update the
Status field the ticket already has, in place and in its own format. Only when parseRequestStatus() returns
null may a field be added, and then a bare > **Status**: <value> line โ not a whole metadata header.
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.
| Item | Budget |
|---|
| Whole ticket | ~100 lines (wc -l). Past 150, the ticket is doing a tech spec's job โ move the design out and link to it |
| Acceptance Criteria | โค 8 substantive (Phase 1.5 splits above that). Gate receipts do not count toward it and are not deducted from the rendered ticket โ a ticket may legitimately render 8 substantive ACs plus its receipts |
| Background | โค 10 lines โ why this exists, not how it will be built |
Progress table | Cells are overwritten, never appended to |
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.
Trimming is authoring, never updating, and never rides along on a correction. --update and
--update-all do not trim at any length: their mutable set is the four fields Phase 4.5 names, and
Background, Requirements, Scope and Related Files are frozen record content however far over budget
the ticket runs. Nor does Phase 4.5's factual-correction exception authorize it โ that exception
covers only what it names (the erroneous fact, or an unfilled template placeholder) and nothing
else in the document. Trimming is not a correction, so it never rides along on one.
Letting a one-line correction carry a rewrite of unrelated sections would reopen the whole record
through the narrowest door in the contract. "The next substantive edit" therefore means authoring
the ticket before it becomes a record; trimming an existing record is a separately authorized
refactor, stated as such.
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 are written per ยง Live Checkbox ACs โ that section owns the syntax; restating it here would make this a second extraction contract, which is the drift this delegation exists to prevent. Authoring a form it does not accept means the ticket could never be updated. A ticket may instead record ACs as an AC โ evidence table; that is a valid form which no update mode can count, so such a ticket is reported and left unmutated rather than verified
After Creation
Request tickets are created after /tech-spec exists (see Relationship section). Suggest execution-oriented next steps:
/feature-dev โ Start implementation following the ticket's Acceptance Criteria
/verify โ Run tests after implementation
/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