/cr -- Change Request Management

Manage the full CR lifecycle: create, update status, branch, audit, and index maintenance.

Parse the user's argument to determine the operation. If no argument or ambiguous, ask.

Project configuration: The CR directory path defaults to docs/change-requests/. If the project CLAUDE.md defines a different location, use that instead.

Status Lifecycle

code

Draft -> Proposed -> Planned -> Implemented -> Archived

Status	Meaning	Spec completeness
Draft	Idea captured, not yet fully designed	Metadata table + Executive Summary only (remaining sections optional)
Proposed	Designed and approved, ready to implement	All sections mandatory and filled
Planned	Approved, scheduled for future	All sections mandatory and filled
Implemented	Done and deployed	All sections + Implementation Date
Archived	Dead, reverted, or merged	Varies -- requires a reason

A CR can be created as either Draft (lightweight idea) or Proposed (full spec). Draft CRs must be promoted to Proposed (with all sections filled) before implementation begins.

Operations

1. `create` -- Create a new CR

Trigger: /cr create <title> or /cr new <title>

Steps (in exact order):

•
Read the index at {cr-dir}/README.md. Find the line Next available CR number: **CR-###**. That number is the CR number to use.
•
Gather requirements -- Ask the user (single AskUserQuestion with up to 4 questions):
- •Status: Draft (idea, lightweight) / Proposed (full spec, ready to implement)
- •Priority: High / Medium / Low
- •Scope: which areas? (Consult CLAUDE.md for project-specific scope categories. If none defined, ask as free text.)
- •Dependencies: does this CR depend on or block any existing CRs? (free text, or "None")

•

Create the spec file at:

code

{cr-dir}/CR-{number}_{snake_case_title}.md

File name uses snake_case (underscores, lowercase). Example: CR-127_voice_activity_detection.md

If status is Draft, use the Draft template (minimal):

markdown

# CR-{number}: {Title}

| Field | Value |
|-------|-------|
| **CR Number** | CR-{number} |
| **Date** | {today YYYY-MM-DD} |
| **Author** | Claude Code |
| **Status** | Draft |
| **Priority** | {High/Medium/Low} |
| **Estimated Scope** | {comma-separated areas} |
| **Related CRs** | {CR-### (description), or None} |
| **Depends On** | {CR-### (reason), or None} |

---

## Executive Summary

{2-4 sentences: what's wrong now + what this CR does about it}

---

## Open Questions

- {what needs to be figured out before this can become Proposed}

If status is Proposed, use the full template (every section mandatory):

markdown

# CR-{number}: {Title}

| Field | Value |
|-------|-------|
| **CR Number** | CR-{number} |
| **Date** | {today YYYY-MM-DD} |
| **Author** | Claude Code |
| **Status** | Proposed |
| **Priority** | {High/Medium/Low} |
| **Complexity** | {Low/Medium/Low-Medium/Medium-High/High} |
| **Estimated Scope** | {comma-separated areas} |
| **Related CRs** | {CR-### (description), or None} |
| **Depends On** | {CR-### (reason), or None} |
| **Breaking Changes** | {Yes/No -- default No} |

---

## Executive Summary

{2-4 sentences: what's wrong now + what this CR does about it}

**Current Problems:**
1. {problem 1}
2. {problem 2}

---

## Problem Analysis

{Current state, why it's insufficient, data/evidence}

---

## Proposed Solution

{Architecture, design, approach. Use code blocks, diagrams, tables as needed.}

---

## Implementation Plan

### Phase 1: {name}

1. {step}
2. {step}

### Phase 2: {name}

1. {step}
2. {step}

---

## Files to Modify/Create

| File | Action | Changes |
|------|--------|---------|
| `path/to/file` | **CREATE** / Modify | {what changes} |

---

## Testing Plan

### Test Case 1: {name}

- {action}
- Verify: {expected result}

---

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| {risk} | Low/Medium/High | Low/Medium/High | {mitigation} |

---

## Rollback

1. {revert step 1}
2. {revert step 2}

---

## Success Criteria

1. {measurable outcome 1}
2. {measurable outcome 2}

---

## References

- {file or URL}
- {related CR}

•
Update the index -- Edit {cr-dir}/README.md:
- •Draft CRs go in the Draft (Ideas & Future Features) table
- •Proposed CRs go in the Proposed (Ready to Implement) table
- •Format: | [CR-{number}](CR-{number}_{snake_case}.md) | {Title} | {Priority} | {Short description} |
- •Increment "Next available CR number" to CR-{number+1}
- •Update the *Last updated:* line at the bottom to today's date and the new CR title
•
Create the git branch (only for Proposed CRs -- Draft CRs do not get branches):
code
```
git checkout -b feature/CR-{number}-{kebab-case-title}
```
Branch name uses kebab-case (hyphens, lowercase). Example: feature/CR-127-voice-activity-detection

•

Stage and commit:

code

git add {cr-dir}/CR-{number}_*.md {cr-dir}/README.md
git commit -m "docs(CR-{number}): add {title} specification"

For Draft CRs, use: docs(CR-{number}): draft {title}

•
Report -- Print summary: CR number, file path, status, branch name (if Proposed), index updated.

2. `status` -- Update CR status

Trigger: /cr status <CR-number> <new-status>

Valid statuses: draft, proposed, planned, implemented, archived

Steps:

•
Read the CR spec file -- Find it via {cr-dir}/CR-{number}_*.md (glob).
•
Update the spec file -- Change the | **Status** | row in the metadata table to the new status.
- •Draft -> Proposed: Verify all mandatory sections exist (Problem Analysis, Proposed Solution, Implementation Plan, Files to Modify, Testing Plan, Risk Assessment, Rollback, Success Criteria, References). If any are missing or still contain placeholder text, warn the user and list what needs to be filled before promoting. Also add | **Complexity** | and | **Breaking Changes** | rows to metadata if missing.
- •-> Implemented: Add/update | **Implementation Date** | {today} | after the Status row.
- •-> Archived: Ask the user for the archival reason.
•
Move in README.md index -- The CR must move between sections:
- •Draft -> Proposed: Move from Draft table to Proposed table
- •Draft -> Planned: Move from Draft table to appropriate Planned subsection
- •Proposed -> Planned: Move from Proposed table to appropriate Planned subsection
- •Proposed or Planned -> Implemented: Move to correct Implemented category. Add date column.
- •Any -> Archived: Move to Archived section. Add Reason column.
•
Update the *Last updated:* line at the bottom of README.md.

•

Stage and commit:

code

git add {cr-dir}/CR-{number}_*.md {cr-dir}/README.md
git commit -m "docs(CR-{number}): update status to {status}"

Category placement for Implemented CRs -- Consult the project CLAUDE.md for project-specific category mappings. If none defined, use scope keywords from the CR to determine placement, or ask the user.

3. `promote` -- Promote Draft to Proposed

Trigger: /cr promote <CR-number>

Shortcut for /cr status <CR-number> proposed with extra guidance.

Steps:

•Read the CR spec file.
•Check completeness -- List which sections are missing or still have placeholder text.
•If sections are missing: fill them using codebase context (read relevant files, grep for related code), then present the updated spec for user review.
•If all sections present: update status to Proposed and move in index.
•Create the git branch: git checkout -b feature/CR-{number}-{kebab-case-title}
•Stage and commit.

4. `branch` -- Create branch for existing CR

Trigger: /cr branch <CR-number>

Steps:

•Read the CR spec to get the title and status.
•If status is Draft, warn: "Draft CRs should be promoted to Proposed before branching. Continue anyway?"
•Create branch: git checkout -b feature/CR-{number}-{kebab-case-title}
•Report the branch name.

5. `list` -- Show CR overview

Trigger: /cr list or /cr list <status>

Steps:

•Read {cr-dir}/README.md.
•If a status filter is given (draft, proposed, planned, implemented, archived), show only that section.
•If no filter, show counts per status and list all Draft + Proposed + Planned CRs (the actionable ones).

6. `next` -- Show next available CR number

Trigger: /cr next

Steps:

•Read {cr-dir}/README.md.
•Find and print the line: Next available CR number: **CR-###**

7. `show` -- Show CR details

Trigger: /cr show <CR-number>

Steps:

•Glob for {cr-dir}/CR-{number}_*.md.
•Read and display the metadata table + executive summary.
•Show current status, priority, dependencies, and which CRs it blocks.

8. `deps` -- Show dependency graph

Trigger: /cr deps or /cr deps <CR-number>

Steps:

•If a CR number is given, read that CR and show its dependency chain (what it depends on, what depends on it).
•If no number, scan all Draft + Proposed + Planned CRs for Depends On and Related CRs fields. Print a dependency tree.

9. `version` -- Record version release with CR

Trigger: /cr version <version> <CR-numbers...>

Example: /cr version v2.22.0 CR-122 CR-125

Steps:

•Read {cr-dir}/README.md.
•
Add entry to the Version History table:
code
```
| {version} | {CR-### Title, CR-### Title} | {today} |
```
Insert at the TOP of the version history table (newest first).
•Update the *Last updated:* line.

•Stage and commit:

code

git add {cr-dir}/README.md
git commit -m "docs: record {version} release ({CR list})"

10. `audit` -- Audit CR structure integrity

Trigger: /cr audit or /cr init

Scans all CR files and the README.md index, identifies inconsistencies, and offers to fix them. Run this periodically or after manual edits to ensure everything stays aligned.

Steps:

•
Scan files -- Glob {cr-dir}/CR-*.md to find all spec files on disk.
•
Read the index -- Parse {cr-dir}/README.md to extract all CR entries from every section (Draft, Proposed, Planned, Implemented, Archived).
•
Run checks -- For each CR, verify the following. Collect all issues into a report organized by severity:

Critical (broken state):
- •Orphaned files: Spec file exists on disk but CR is not in README.md index
- •Broken links: CR appears in README.md with a link but the file doesn't exist
- •Status mismatch: Status in spec file metadata doesn't match the README.md section it's listed in
- •Duplicate entries: Same CR number appears in multiple index sections
Warning (data quality):
- •Missing Implementation Date: CR is in Implemented section but spec file lacks | **Implementation Date** | row
- •Missing Complexity/Breaking Changes: CR is Proposed or above but lacks | **Complexity** | or | **Breaking Changes** | rows
- •Incomplete Proposed spec: CR is Proposed but missing mandatory sections (Problem Analysis, Proposed Solution, Implementation Plan, Files to Modify, Testing Plan, Risk Assessment, Rollback, Success Criteria, References)
- •Filename convention: Spec file doesn't follow CR-{number}_{snake_case}.md pattern
Info (cosmetic):
- •Plain-text CRs without files: CR in index listed as plain text (no link) -- acceptable for legacy but flagged for awareness
- •Next CR number check: Verify Next available CR number is actually the highest CR number + 1
- •Stale last-updated: The *Last updated:* line is more than 30 days old

•

Print the report -- Format as a structured summary:

code

## CR Audit Report

Scanned: {N} files on disk, {M} entries in index

### Critical ({count})
- [issue description]

### Warnings ({count})
- [issue description]

### Info ({count})
- [issue description]

### Summary
{pass/fail} -- {count} issues found ({critical} critical, {warnings} warnings, {info} info)

•
Offer to fix -- If any Critical or Warning issues were found, ask the user:
- •"Fix all automatically?" -- Apply all safe fixes (add missing metadata rows, move entries between sections, add orphaned files to index)
- •"Fix selectively?" -- Walk through each issue one at a time
- •"Report only" -- Just show the report, don't change anything
•
Apply fixes (if authorized):
- •Orphaned files: Read the spec file, extract status/title/priority, add to correct README.md section
- •Broken links: Convert linked entry [CR-###](...) to plain text CR-### in index, or remove if the CR never existed
- •Status mismatch: Move the CR to the correct README.md section matching its spec file status (spec file is source of truth for status)
- •Missing Implementation Date: Add | **Implementation Date** | {date from Implemented table, or today} | to spec
- •Missing Complexity/Breaking Changes: Add rows with sensible defaults (Medium / No)
- •Next CR number: Update to highest found + 1

•

Stage and commit (if fixes were applied):

code

git add {cr-dir}/
git commit -m "docs(cr): audit -- fix {N} issues"

•
Re-run report after fixes to confirm clean state.

Notes:

•The spec file is the source of truth for status. If spec says "Implemented" but index has it under "Proposed", the fix is to move it in the index.
•For CRs with no spec file (plain text in index), these are legacy entries -- flag but don't treat as errors.
•This operation never deletes files or removes index entries without explicit user confirmation.

Rules (always enforced)

Numbering

•Sequential integers. CR-127, CR-128, CR-129. Never skip. Never reuse. No year prefix.
•Source of truth: the Next available CR number line in {cr-dir}/README.md.

Files

•One CR = one file. Never put two CRs in a single spec file.
•File name = snake_case. CR-127_my_feature.md. Never kebab-case in filenames.
•Branch name = kebab-case. feature/CR-127-my-feature. Never snake_case in branches.
•Draft CRs do not get branches. Only Proposed and above.

Templates

•Draft: metadata table + Executive Summary + Open Questions. Everything else optional.
•Proposed and above: all sections mandatory. No placeholders, no TODOs.
•Fill with best-effort content; the user will refine.

Index

•README.md is the master index. Every CR must appear in it. A CR that exists as a file but isn't in the index is broken.
•Status in spec file and README.md must match. When updating status, update both.
•Draft CRs go in the Draft section. Proposed CRs go in the Proposed section.
•CRs without spec files are listed as plain text (CR-### not [CR-###](...)). This is only for legacy lightweight changes. All new CRs must have spec files.

Status transitions

•Draft -> Proposed: All sections must be filled. Complexity and Breaking Changes fields added. Branch created.
•Draft -> Planned: Allowed (idea parked for later). Full spec not required yet.
•Proposed -> Implemented: Implementation Date added.
•Any -> Archived: Reason required. Always ask.
•Phased CRs may add rows: | **Phase N Completed** | {date} |. Status stays Implemented only when ALL phases complete. Use Implemented (Phase 1-2 Complete) for partial.

Formatting

•Dates: ISO 8601 YYYY-MM-DD.
•Commit messages: {type}(CR-{number}): {description} -- types: docs, feat, fix, refactor, chore.

Boundaries

•Never touch CHANGELOG.md from this skill. Changelog updates happen during /commit or manual release.
•Archived CRs require a reason. Always ask for the archival reason.
•When a CR is implemented, the date in the Implemented table is the date it was moved to Implemented, not the spec creation date.

/cr -- Change Request Management

Status Lifecycle

Operations

1. create -- Create a new CR

2. status -- Update CR status

3. promote -- Promote Draft to Proposed

4. branch -- Create branch for existing CR

5. list -- Show CR overview

6. next -- Show next available CR number

7. show -- Show CR details

8. deps -- Show dependency graph

9. version -- Record version release with CR

10. audit -- Audit CR structure integrity

Rules (always enforced)

Numbering

Files

Templates

Index

Status transitions

Formatting

Boundaries

1. `create` -- Create a new CR

2. `status` -- Update CR status

3. `promote` -- Promote Draft to Proposed

4. `branch` -- Create branch for existing CR

5. `list` -- Show CR overview

6. `next` -- Show next available CR number

7. `show` -- Show CR details

8. `deps` -- Show dependency graph

9. `version` -- Record version release with CR

10. `audit` -- Audit CR structure integrity