Typed Artifacts: Surface Routing
When you notice something you cannot act on in this session, do NOT bury it in prose. Route it to a typed artifact via one of the slash commands.
The routing table
| If you're about to write… |
Use this command |
Lands in |
| "pre-existing", "already existed", "introduced before" |
/quirk:artifacts:bug |
BUGS.md |
| "out of scope", "future work", "larger refactor needed" |
/quirk:artifacts:defer |
DEFERRED.md |
| "skipped for brevity", "tests can be added later" |
/quirk:artifacts:test-skip |
TEST_BACKLOG.md |
| "worth reconsidering", "architectural concern", "worth revisiting" |
/quirk:artifacts:triage (proposal) |
proposals.md |
| "we made an architectural decision" |
/quirk:artifacts:adr |
docs/adr/NNNN-*.md |
| Don't know which fits |
/quirk:artifacts:triage |
one of the above |
After appending, continue the current task. Do NOT stop to discuss the routing entry unless severity is critical. The artifact is the discussion.
Schemas (summary)
Full schemas live in the templates/ directory of the quirk plugin. Required fields per artifact:
- BUGS.md (BUG-N): title, file (path:line), description, severity (critical/high/medium/low)
- DEFERRED.md (DEFER-N): title, why_deferred, priority (P1/P2/P3/P4)
- TEST_BACKLOG.md (TEST-N): title, file_under_test, reason_skipped
- proposals.md (PROPOSAL-N): title, context, recommendation
- docs/adr/NNNN-*.md (Nygard): title, status (proposed → accepted → superseded)
The mutation scripts re-validate required fields. Missing fields surface as a clarifying question — never invent values.
When NOT to route
- The observation is the work you're doing right now → fix it, don't log it.
- The observation is a bug you just introduced this session → fix it, don't log it. The "Introduced by" field on BUGS.md is for things that pre-date your session.
- The observation is information about the user's intent → ask, don't log.
First-time setup
If the user hasn't run /quirk:artifacts:init in this project yet, suggest it. Without artifact files in the project root, the append commands will exit 3.
Review cadences
(Declared in the user's CLAUDE.md when /init runs.)
- BUGS.md — every PR
- DEFERRED.md — every sprint planning
- TEST_BACKLOG.md — every 2 weeks
- proposals.md / docs/adr/ — monthly with architect
Use /quirk:artifacts:review-artifacts to scan all four files in one read-only pass.
1---2name: typed-artifacts3description: Use when about to write hedging language like "pre-existing", "out of scope", "future work", "skipped for brevity", or "architectural concern" — instead, route the observation to a typed artifact (BUGS.md, DEFERRED.md, TEST_BACKLOG.md, proposals.md) or an ADR. Also use when the user invokes /quirk:artifacts:* commands or asks how to log a bug, defer a task, or record a decision.4---56# Typed Artifacts: Surface Routing78When you notice something you cannot act on in this session, do NOT bury it in prose. Route it to a typed artifact via one of the slash commands.910## The routing table1112| If you're about to write… | Use this command | Lands in |13|---|---|---|14| "pre-existing", "already existed", "introduced before" | `/quirk:artifacts:bug` | `BUGS.md` |15| "out of scope", "future work", "larger refactor needed" | `/quirk:artifacts:defer` | `DEFERRED.md` |16| "skipped for brevity", "tests can be added later" | `/quirk:artifacts:test-skip` | `TEST_BACKLOG.md` |17| "worth reconsidering", "architectural concern", "worth revisiting" | `/quirk:artifacts:triage` (proposal) | `proposals.md` |18| "we made an architectural decision" | `/quirk:artifacts:adr` | `docs/adr/NNNN-*.md` |19| Don't know which fits | `/quirk:artifacts:triage` | one of the above |2021After appending, **continue the current task**. Do NOT stop to discuss the routing entry unless severity is `critical`. The artifact is the discussion.2223## Schemas (summary)2425Full schemas live in the `templates/` directory of the quirk plugin. Required fields per artifact:2627- **BUGS.md** (BUG-N): title, file (path:line), description, severity (critical/high/medium/low)28- **DEFERRED.md** (DEFER-N): title, why_deferred, priority (P1/P2/P3/P4)29- **TEST_BACKLOG.md** (TEST-N): title, file_under_test, reason_skipped30- **proposals.md** (PROPOSAL-N): title, context, recommendation31- **docs/adr/NNNN-*.md** (Nygard): title, status (proposed → accepted → superseded)3233The mutation scripts re-validate required fields. Missing fields surface as a clarifying question — never invent values.3435## When NOT to route3637- The observation is the work you're doing right now → fix it, don't log it.38- The observation is a bug **you just introduced this session** → fix it, don't log it. The "Introduced by" field on BUGS.md is for things that pre-date your session.39- The observation is information about the user's intent → ask, don't log.4041## First-time setup4243If the user hasn't run `/quirk:artifacts:init` in this project yet, suggest it. Without artifact files in the project root, the append commands will exit 3.4445## Review cadences4647(Declared in the user's CLAUDE.md when `/init` runs.)4849- BUGS.md — every PR50- DEFERRED.md — every sprint planning51- TEST_BACKLOG.md — every 2 weeks52- proposals.md / docs/adr/ — monthly with architect5354Use `/quirk:artifacts:review-artifacts` to scan all four files in one read-only pass.
zpyoung