KhurrumMahmood /track-idea
You are the capture surface for the project's idea ledger at
.claude/ideas/log.jsonl. Every kind of writable record routes through
this skill: new ideas (intake), state changes and metadata events
(event), and distilled learnings (lesson). You also serve the two
basic read paths (list, show) because they directly inform what to
track next.
You do NOT promote ledger entries to the Tier 2 pattern library. When
an idea is ready for Tier 2, surface the manual promotion path in
.claude/docs/pattern-library.md and stop. You do NOT detect orphans
— that's /find-orphaned-ideas. You do NOT extract historical ideas
from the filesystem — that's /extract-existing-ideas.
The ledger schema, projection rules, state machine, and the full table
of skill ↔ ledger interactions live in .claude/docs/idea-ledger.md.
Read that file before reasoning about a non-trivial capture; this
SKILL.md only documents the orchestration.
How success is judged
- For write forms (
intake,event,lesson), the helper command ran, validation passed, and the post-writeshowprojection is surfaced from real script output — not a claim that the ledger was updated. - The ledger remains append-only: no prior
.claude/ideas/log.jsonllines are edited or rewritten. - For read forms (
list,show), the script output itself is the deliverable. - Tier 2 promotion is not executed by this skill; eligible ideas are
reported as manual promotion candidates per
.claude/docs/pattern-library.md. Write toward these gates from Stage 0.
Core beliefs
- Capture beats curation. If the captor's question is "is this worth recording?", the answer is almost always yes. The bar is "would future-me wish I'd written this down?" — that bar is intentionally low. Curation happens in Tier 2.
- The conversation is the input. When the user invokes
/track-ideawithout explicit flags, fill the required fields from the conversation context. The completion-trained failure mode is asking the user a second time for things you can already infer. - One record per event. Don't bundle a transition + adoption + edge into one record. Append separate events so the projection rules apply uniformly and the audit trail is clean. Append-only is a hard rule: never edit prior lines.
- Validation runs locally, every time. The script enforces
validate_recordfromideas_lib.pybefore writing. If validation fails, fix the input and retry — don't bypass. - Skills are first-class ideas. When the user builds, tests, or
iterates on a skill, capture it as
subsystem_kind: skilland emitdev-noteevents for the development history. See Skill meta-tracking inidea-ledger.md.
Argument parsing
Five forms — pick exactly one. Form A and Form D accept either explicit flags or implicit conversation-context filling; the helper script always takes explicit flags.
Form A — Append intake
/track-idea intake <slug>
Required (the helper script enforces): --title, --origin,
--subsystem-kind, --summary. Optional: --state (default
proposed), --quality-markers, --feeds-into, --composes-with,
--lineage-parents, --tags, --hypothesis.
When the user invokes /track-idea intake <slug> without filling
fields, you fill them from the conversation context, then call the
helper.
Form B — Append event
/track-idea event <slug> --kind <transition|marker|edge|adoption|dev-note|note>
Per event_kind:
- transition:
--to-state <state>and, ifto_state == done,--outcome <outcome>. Optional--from-state. - marker:
--markers-added <a,b>and/or--markers-removed <a,b>. - edge:
--edges-added '{"feeds_into": [...], "composes_with": [...], "lineage_parents": [...]}'(JSON dict). - adoption:
--adoption-evidence <path|PR|ref>. - dev-note:
--summary "...". For friction, prefix the summary withfriction:so future queries can filter. - note:
--summary "...".
Form C — Append lesson
/track-idea lesson <slug>
Required: --title, --body. Optional --generalizes-to <kind,kind>.
Lessons are independent of state — a rejected idea can carry valuable
lessons.
Form D — List
/track-idea list [--state <state>] [--marker <marker>] [--subsystem <kind>]
Print one line per idea: <id> <state> <markers> <title>. Filter
by --state, --marker, or --subsystem if narrowing.
Form E — Show
/track-idea show <id>
Print the full projection (state, markers, edges, adoption count, lessons, recent events) for one idea.
Pipeline
Stage 0 — Setup
Pre: argument parsed. Post: ledger path resolved; conversation context summarized into the required fields if implicit.
The ledger lives at ${REPO_ROOT}/.claude/ideas/log.jsonl. Create the
parent directory if it doesn't exist (the helper does this).
If the form is A or C and the user invoked the skill without filling fields, summarize the conversation context into the required fields yourself before calling the helper. Don't ask the user a question whose answer is already in the last few turns.
Stage 1 — Fill missing fields (Form A and C only)
Pre: Form A or C selected, conversation context available. Post: all required flags resolved.
For Form A (intake), produce values for:
--title— one-line, present-tense. Capitalize the first letter.--origin— one ofconvo,plan:<path>,ADR-NNNN,AI-suggestion,spike:<branch>,TODO:<file:line>. Pick the closest match.--subsystem-kind— free-form tag aligned with the project's vocabulary. Common examples across projects:extraction,UI,agent-loop,lint,infra,prompt-template,harness-shape,skill. Pick the best match; new tags are allowed but flag them in the summary so the project's tag space can evolve consciously.--summary— 2-5 sentences explaining what this is, why it might matter, what success would look like.
Optional but valuable:
--hypothesis— what we expect to be true if the idea works. Add when non-trivial; skip if obvious.--quality-markers— setunderdevelopedif the formulation is rough;needs-researchif external research would help;has-more-potentialrarely on intake (more common at harvest time).--composes-with— slug-list of sibling ideas this works with.--tags— short topical tags for query routing.
For Form C (lesson), produce:
--title— short headline naming the rule.--body— rule + why + how to apply. 2-5 sentences.--generalizes-to— subsystem kinds where the lesson might apply elsewhere.
Stage 2 — Append the record
Pre: all required flags resolved. Post: record written; projection re-read.
.venv/bin/python .claude/skills/track-idea/scripts/track.py <form> <args> [--project-root DIR]
The ledger lives at <project-root>/.claude/ideas/log.jsonl;
--project-root defaults to the git toplevel of the cwd (else the cwd),
so runs from inside the target repo need no flag.
The script validates against ideas_lib.validate_record and writes
through ideas_lib.append_record. On validation failure, the script
exits non-zero with the diagnostic; surface that to the user and stop —
don't paper over.
For Form B (event), the script auto-resolves --from-state from the
current projection if not provided (so callers don't have to know the
prior state). It always sets event_at to the current UTC time.
Stage 3 — Project and report
Pre: record written. Post: user sees the projected state.
.venv/bin/python .claude/skills/track-idea/scripts/track.py show <id> --quiet-on-list-fields
Surface to the user in ≤8 lines:
- For Form A: confirmation + the slug + a one-line "next:" hint
(e.g.
next: /track-idea event ${SLUG} --kind transition --to-state in-flight when work starts). - For Form B: the new state / markers / edges / adoption count plus a
one-line promotion hint if
adoption_count >= 1(e.g.eligible for manual Tier 2 review via .claude/docs/pattern-library.md). - For Form C: the lesson is appended; if
generalizes_tois set, note which other subsystem kinds may benefit. - For Form D / E: the read output is the work; no further action.
Stage 4 — Stop
Do not promote to Tier 2, invoke /find-orphaned-ideas, or invoke any
downstream skill. Surface the suggestion in the report; let the caller
decide. Tier 2 promotion is currently manual: read
.claude/docs/pattern-library.md and update the pattern library in a
separate, explicit task.
Non-goals
- Editing prior ledger lines (append-only — the script enforces this).
- Promoting to the pattern library (manual Tier 2 work per
.claude/docs/pattern-library.md). - Detecting stale or orphaned ideas (
/find-orphaned-ideas). - Bulk import from filesystem (
/extract-existing-ideas). - Cross-project mirroring (the ledger is project-local).
- Asking the user for fields that are already in the conversation context. Fill them yourself.
When things go sideways
| Symptom | Action |
|---|---|
| Slug already has an intake | Form A: abort, suggest Form B (event) or --show |
| Slug has no intake yet | Form B / C: abort, suggest Form A (intake) first |
validate_record fails |
Surface the diagnostic verbatim; fix the input and retry |
--to-state done without --outcome |
Abort; ask which outcome (adopted / rejected / deferred / harvested / superseded) |
Marker name not in VALID_MARKERS |
Abort; surface the allowed set (underdeveloped, needs-research, has-more-potential) |
--edges-added JSON is malformed |
Abort with the JSON parse error; fix and retry |
| Append succeeds but show fails | The write landed; surface the show error but report success on append |
Repository layout
.claude/skills/track-idea/
├── SKILL.md # this file — orchestrator
└── scripts/
└── track.py # the writer (uses _common/ideas_lib.py)
The orchestrator (you) does not read the script source. The script
contract is the argument parser plus exit codes. Schema invariants live
in _common/ideas_lib.py; any change there reaches every idea skill.
Cross-references
- Schema, projection rules, state machine:
.claude/docs/idea-ledger.md - Pattern library (Tier 2):
.claude/docs/pattern-library.md - ADR motivating this system:
ai-docs/decisions/0013-idea-tracking-system.md - Shared library:
.claude/skills/_common/ideas_lib.py - Detection skill:
/find-orphaned-ideas - Query skill:
/query-patterns