| name | claude-tweaks:capture |
| description | Use when capturing ideas that need specification later — brain dumps, half-formed features, things to not forget |
Interaction style: Present single decisions via the AskUserQuestion tool (options with one marked Recommended) instead of a plain-text numbered list. For multi-item decisions, render a batch table with recommended actions pre-filled, then capture the apply-all/override decision via one AskUserQuestion call. Never make more than one AskUserQuestion call per logical decision — resolve each before showing the next. End skills with a ## Next Actions block rendered via AskUserQuestion (context-specific options, one recommended), not a navigation menu.
Capture — Quickly note an idea for later specification
Quick capture for ideas that aren't ready for full specification. Part of the workflow lifecycle:
/claude-tweaks:init → [ /claude-tweaks:capture ] → /claude-tweaks:challenge → /superpowers:brainstorming → /claude-tweaks:specify → /claude-tweaks:build → /claude-tweaks:stories → /claude-tweaks:test → /claude-tweaks:review → /claude-tweaks:wrap-up
^^^^ YOU ARE HERE ^^^^
When to Use
- User mentions something that should be a feature but isn't specified
- Discovery during implementation reveals something that needs its own spec
- "We should probably..." or "Don't forget to..." moments
- Anything that would otherwise be lost or forgotten
Backlog vs parked: Use /claude-tweaks:capture for new ideas and half-formed features — these land as fresh backlog records: no stage label under work-backend: github-issues, no stage: frontmatter under work-backend: local-files. Work deferred from an active build/review goes through /claude-tweaks:tidy's Defer action instead — the existing record gains the parked label (github-issues) or stage: parked frontmatter (local-files) plus a trigger. Either way a deferred record carries origin context, file references, and a timing trigger that a fresh backlog record doesn't have. See _shared/work-record.md for the full stage vocabulary (backlog / parked / ready).
Input
$ARGUMENTS is parsed as <idea text> [--route=<value>]:
| Argument | Behavior |
|---|
| Free-text idea | The body of the new backlog record (title is derived from the first phrase or supplied via --title=). |
--route=challenge / --route=brainstorm / --route=keep / --route=absorb:N | Skip the post-capture routing prompt; apply the route directly. Legacy --route values are still accepted as aliases — see Immediate Routing. |
--title="..." | Override the auto-derived title. |
When $ARGUMENTS is empty, prompt the user for the idea body.
Workflow
| Step | What |
|---|
| 1 | Add the record — GitHub issue via recordPayload, or a specs/{id}-{slug}.md record via local-store.js, per Backend Selection below. |
| 2 | Route per --route arg, or via the Routing Prompt below. |
| 3 | Commit (when this is a standalone invocation; component-skill callers commit themselves). work-backend: github-issues captures have nothing new to commit unless the failure fallback wrote a local specs/{id}-{slug}.md record, or the route was absorb:N (which edits the target record locally regardless of backend). |
Backend Selection
Read the work-backend field from the project's CLAUDE.md (under a ## Work records section, written by /claude-tweaks:init). backlog-backend — the pre-migration flag name, under ## Backlog integration — is accepted as a read-only legacy alias. A missing flag is treated as local-files — same missing-flag convention as design-integration.
$TITLE/$BODY/$TYPE below are the same fields Entry Format and Adding an Entry (further down) have always asked for: $BODY is the **Related:**/Context:/Scope: block assembled per Entry Format; $TYPE is the guessed-then-confirmed Type from Adding an Entry.
When work-backend: github-issues:
-
Bootstrap per _shared/label-bootstrap.md, LABELS_JSON:
When the project's work-types key reads labels, also bootstrap the guessed type:{t} label the same way — its pair lives in record.js's TYPE_LABELS (e.g. ['type:bug', 'Type: a defect in existing behavior'] when the guess is bug).
-
Build the payload via recordPayload and create the issue:
node -e "const {recordPayload}=require(process.env.CLAUDE_PLUGIN_ROOT+'/bin/lib/issues/record.js');
const p=recordPayload({title:process.argv[1], body:process.argv[2], type:process.argv[3], origin:'capture'});
require('fs').writeFileSync('/tmp/capture-payload.json', JSON.stringify(p))" "$TITLE" "$BODY" "$TYPE"
node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/capture-payload.json','utf8')).body)" > /tmp/capture-body.md
Type expression branch. Read the project's work-types config key once before filing and branch — never re-probe mid-flow (_shared/work-record.md's config-key table; the key is written by /init). work-types: native applies $TYPE via GitHub's native Issue Type; work-types: labels adds the matching type:$TYPE label instead (the pairs live in record.js's TYPE_LABELS):
gh issue create \
--title "$TITLE" \
--body-file /tmp/capture-body.md \
--type "$TYPE" \
--label by:capture
gh issue create \
--title "$TITLE" \
--body-file /tmp/capture-body.md \
--label by:capture \
--label "type:$TYPE"
-
On failure (GitHub unreachable, gh broken, transient API error): fall back to the local driver — write the record via local-store.js, using the same slug derivation rule as the local-files branch below:
node -e "const {writeRecord, allocateId}=require(process.env.CLAUDE_PLUGIN_ROOT+'/bin/lib/issues/local-store.js');
const id = allocateId('specs');
writeRecord(\`specs/\${id}-\${process.argv[1]}.md\`, {
title: process.argv[2],
body: process.argv[3],
facets: { type: process.argv[4], origin: 'capture', unsynced: true }
});
console.log('specs/' + id + '-' + process.argv[1] + '.md')" "$SLUG" "$TITLE" "$BODY" "$TYPE"
Tell the user issue creation failed and the record landed locally instead (path printed above), unsynced: true. No further marker is needed beyond that facet — /claude-tweaks:tidy's record scan surfaces unsynced local records as Sync findings, reconciling them onto GitHub on a later pass.
When work-backend: local-files (or the flag is missing):
Write the record via local-store.js directly — no unsynced facet (there is no GitHub side to reconcile against):
node -e "const {writeRecord, allocateId}=require(process.env.CLAUDE_PLUGIN_ROOT+'/bin/lib/issues/local-store.js');
const id = allocateId('specs');
writeRecord(\`specs/\${id}-\${process.argv[1]}.md\`, {
title: process.argv[2],
body: process.argv[3],
facets: { type: process.argv[4], origin: 'capture' }
});
console.log('specs/' + id + '-' + process.argv[1] + '.md')" "$SLUG" "$TITLE" "$BODY" "$TYPE"
Derive {slug} from the title: lowercase, replace runs of non-alphanumeric characters with a single -, trim leading/trailing -, truncate to 60 characters; on a collision with an existing file, append -2, -3, etc. allocateId('specs') assigns the numeric {id} prefix.
Entry Format
Both drivers share the same body shape — this is $BODY in Backend Selection above:
**Related:** {optional related record numbers, or "none"}
Context: 1-2 sentences on why this came up or what triggered it
Scope: Rough sense of what it might involve (can be vague)
work-backend: github-issues — this becomes the issue body; the issue title ($TITLE) is the short entry title.
work-backend: local-files — this becomes the record body under the frontmatter; local-store.js's writeRecord composes the # {title} heading above it automatically.
Hard cap: ~5 lines per entry
If it takes more than 5 lines to describe, it's past the raw-capture stage — run /superpowers:brainstorming on it instead. Applies to both drivers.
Adding an Entry
Both drivers run Backend Selection above; don't overthink — capture the essence.
Guessing the Type
Type is guessed from the idea's title/body text — advisory only:
| Title/body contains | Guessed Type |
|---|
fix, broken, crash, error, bug, regression, wrong, fails | bug |
add, support, enable, new, allow, feature | feature |
| none of the above | task |
The guess rides in the existing "Added: '{title}' (Type: {t})" presentation (see Immediate Routing below) — no new question is added. The user overrides via free text in the next message.
Immediate Routing
After adding the record, route the item per the --route arg or by asking.
Routing via --route arg (front-loaded)
/claude-tweaks:capture accepts --route={challenge|brainstorm|keep|absorb:N} to skip the post-capture prompt:
--route value | Action |
|---|
challenge | Open /claude-tweaks:challenge with the new backlog record as input |
brainstorm | Open /superpowers:brainstorming with the new backlog record as input |
keep | Record stays in backlog state — explicitly, no label asserts this; no further routing |
absorb:42 | Absorb the record into record #42; close the new record as not-planned |
Legacy route values inbox and merge:N are accepted as aliases for keep and absorb:N.
When --route is provided, log:
AUTO {time} — Routing: applied --route={value} for backlog record "{title}".
No further prompt. Proceed directly to the routed skill or commit.
Routing prompt (when --route not provided)
In auto mode, apply the silences-table row for /capture from _shared/auto-mode-contract.md: if --route was passed, honor it; otherwise default to keep (the most conservative route — the record stays in backlog state for periodic review at /tidy, no further write that wouldn't have happened anyway). Log:
AUTO {time} — Routing: defaulted to keep (no --route provided). Reversibility: high (record stays in backlog state; user can re-route via /tidy at any time).
In interactive mode (or when explicitly opted in), present "Added: '{title}' (Type: {t})" and call AskUserQuestion:
question: "What should happen with this?", header: "Route idea", multiSelect: false- Option 1 —
label: "Challenge first", description: "Run /claude-tweaks:challenge to stress-test assumptions, then /superpowers:brainstorming, then /claude-tweaks:specify"
- Option 2 —
label: "Brainstorm directly", description: "Run /superpowers:brainstorming to explore the idea now, then /claude-tweaks:specify"
- Option 3 —
label: "Keep as backlog record", description: "Not ready yet, will be reviewed during /claude-tweaks:tidy"
- Option 4 (conditional) —
label: "Absorb into record {N}", description: "This belongs in an existing record"
The call has 4 options only when Option 4 is visible; otherwise build it with the first 3 options only — never include Option 4 with a placeholder value.
Option 4 visibility: Search for a candidate match on the topic keywords from the new backlog record, per the active driver from Backend Selection. local-files — search specs/ for a record matching the keywords. github-issues — search open issues: gh issue list --search "{keywords}" --state open --json number,title --limit 5. Only show option 4 when either search returns a candidate. Without a candidate match, option 4 is omitted entirely — manual disambiguation against an unspecified record number is worse than no option at all.
Route execution, by backend
| Route | local-files | github-issues |
|---|
challenge / brainstorm | Opens the child skill with the record's text as input | Opens the child skill with the issue title + body as input (reference #{issue-number}) |
keep | No further action — the record stays as-is at specs/{id}-{slug}.md, no stage: frontmatter | No further action — the issue is already open, by:capture-labeled, with no stage label. That is the backlog state; there is nothing to add. |
absorb:N | Integrate into record N's body (its Deliverables/AC/Technical Approach sections when shaped, otherwise its raw body), delete the absorbed record's file | Integrate into record #N's body the same way, then comment Absorbed into #N., then gh issue close {n} --reason "not planned" — mirrors /claude-tweaks:tidy's Merge action |
This ensures every captured idea has an explicit next step — either immediate action or a conscious decision to keep it in backlog state.
Good entries:
- "Voice command to add item to shopping list" — context explains the need
- "Recipe nutrition facts display" — scope hints at UI + data needs
Bad entries:
- Just "nutrition" — too vague to act on later
- Full spec with 20 tasks — that's a spec, not a backlog record
- Notes about an existing spec ("spec 50 needs review") — put that on the spec itself
Review Workflow
Periodically (or when the backlog gets long), use /claude-tweaks:tidy to batch-review all backlog records with recommended actions.
Next Actions
When invoked by a parent skill, omit this block — the parent owns the handoff. When invoked directly by a user, call AskUserQuestion:
question: "What's next?", header: "Next step", multiSelect: false- Option 1 —
label: "Capture another idea (Recommended)", description: "/claude-tweaks:capture {next idea} — capture another idea while you're in brainstorming flow"
- Option 2 —
label: "Tidy backlog", description: "/claude-tweaks:tidy — review and triage backlog records (promote, absorb, or drop stale items)"
- Option 3 —
label: "Specify", description: "/claude-tweaks:specify {ref} — promote this record straight to a spec ({ref} is '#{n}' under work-backend: github-issues, or the record id under work-backend: local-files)"
- Option 4 —
label: "Challenge", description: "/claude-tweaks:challenge \"{title}\" — debias and stress-test assumptions before specifying"
Component-Skill Contract
This skill is a component skill — directly invoked by /claude-tweaks:build (Common Step 4, design-mode follow-up capture). /claude-tweaks:visual-review, /claude-tweaks:reflect, /claude-tweaks:wrap-up, and /claude-tweaks:demo file a new backlog record directly without going through this skill, so they are NOT capture parents — they only recommend /capture in Next Actions for the user's next session.
Capture is also a parent of /challenge when --route=challenge is set — when invoking /challenge, capture sets $PIPELINE_RUN_DIR to a standalone run dir (per _shared/pipeline-run-dir.md step 3) if not already set, so the child's auto-mode and audit-log behavior resolves correctly.
Parent invocation of /capture is signaled by $PIPELINE_RUN_DIR being set in the environment (/build running inside /flow). When invoked from within a parent's workflow, omit the ## Next Actions block — the parent owns the handoff. When invoked directly by a user (no PIPELINE_RUN_DIR), render Next Actions as shown above.
Side effect of $PIPELINE_RUN_DIR-based detection: if a user invokes /capture directly while an active /flow pipeline is running, Next Actions are suppressed because the env var is set. This is intentional — pipeline-mid-flow handoff suggestions would conflict with the orchestrator's flow.
Anti-Patterns
| Pattern | Why It Fails |
|---|
| Capturing an idea that already has a spec | Duplicates intent across two files — annotate the spec directly instead so the durable record stays the source of truth |
| Writing a full spec as a backlog record | A backlog record is for half-formed ideas; a fully-formed spec belongs in specs/ where /build and /flow can act on it |
| Never reviewing the backlog | Without periodic triage via /claude-tweaks:tidy, the backlog becomes a graveyard and captured ideas lose context over time |
| Adding implementation details to a backlog record | A backlog record captures what and why — how is brainstorming + spec territory and changes faster than the idea itself |
Skipping /superpowers:brainstorming and jumping straight to specs | Brainstorming surfaces assumptions and constraints that specs need; without it, specs encode unchallenged premises |
| Putting notes about existing specs into a new backlog record | Notes drift from the spec they describe — annotate the spec file directly so the note moves with the work |
Relationship to Other Skills
| Skill | Relationship |
|---|
/claude-tweaks:challenge | Debiases backlog records before /superpowers:brainstorming — /claude-tweaks:help flags candidates |
/superpowers:brainstorming | Explores promoted backlog records — produces design docs |
/claude-tweaks:specify | Shapes captured records to spec shape (adds ready + scoring) — the primary capture→specify path; also decomposes brainstormed design docs into ready leaf records |
/claude-tweaks:review-backlog | Consumes and enriches the **Related:** field this skill's Entry Format stamps — review-backlog is the only skill that suggests values for it, always human-confirmed. |
/claude-tweaks:tidy | Reviews the backlog for stale records — promotes, absorbs, or deletes |
/claude-tweaks:review | May file new backlog records for ideas discovered during review |
/claude-tweaks:wrap-up | May file new backlog records for genuinely new ideas; leftover work becomes a parked record instead |
/claude-tweaks:demo | May file a linked follow-up backlog record when a human requests changes during acceptance review — references the original via an Origin: demo changes-requested from #N body line instead of a by:* label |
/claude-tweaks:build | Calls /capture during Common Step 4 (design mode) to file blocked items and follow-up ideas before they slip |
/claude-tweaks:init | After bootstrap, /init suggests /capture as the entry point for capturing ideas that surface during setup but aren't ready to specify |
/claude-tweaks:reflect | Surfaces tangential ideas at the Wrap-Up Review Console (files new backlog records directly, not via /capture) |
/claude-tweaks:visual-review | UI ideas surfaced during visual review (creative improvements, follow-ups) file as new backlog records via /capture instead of inflating the current spec |
_shared/work-record.md | Taxonomy home — stage vocabulary (backlog / parked / ready), the permission-matrix row for /capture (by:capture + Type only), and the seven-axis label contract this skill files against |
/claude-tweaks:research | Research findings can be captured as backlog records; invoke /research when a backlog record needs evidence before specifying. |
/claude-tweaks:code-health | /code-health routes fuzzy or below-threshold findings to the backlog via /capture instead of filing a GitHub issue, so they get human triage before promotion. |
_shared/auto-mode-contract.md | Single source of truth for auto-mode behavior — read before adding any auto-mode handling |
