This is a documented schema: the actual files and directories depend on the project and are not implied by this catalog.
CategoryContext and rules7 artifacts
CLAUDE.md
Defines how project instructions, safety boundaries, and verification commands are captured for a bounded, reviewable engineering workflow.
Present in repository
A reader-facing CLAUDE.md record that keeps project instructions, safety boundaries, and verification commands explicit for review.
Where it lives
{project}/CLAUDE.md(repository; present in repository)
.claude/CLAUDE.md(repository; documented example)
Fields
commandsconventional — Commands and checks that make the workflow reproducible for CLAUDE.md. Example: npm run check
conventionsconventional — Naming, architecture, and style rules that keep changes consistent for CLAUDE.md.
forbidden actionsconventional — Actions that require an explicit decision before execution for CLAUDE.md.
report formatconventional — The expected shape of findings, evidence, and limitations for CLAUDE.md.
Template CLAUDE.md
# CLAUDE.md
## Commands
- check: `npm run check`
- test: `npm test`
## Rules
- Keep changes inside the task scope.
- Report changed files and verification results.
## Do not
- Read or edit secrets without explicit approval.
When to use
Use CLAUDE.md when you need a durable record of project instructions, safety boundaries, and verification commands, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CLAUDE.md to replace execution evidence, approval, or a record whose responsibility is outside project instructions, safety boundaries, and verification commands.
local preferencesconventional — Personal workflow choices that do not belong in shared policy for CLAUDE.local.md.
machine contextconventional — Paths and environmental facts specific to one workstation for CLAUDE.local.md.
Template CLAUDE.local.md
# CLAUDE.local.md
## Local context
- Database: localhost:<port>
- Fixture directory: <local-path>
## Preferences
- Explain the plan before multi-file changes.
When to use
Use CLAUDE.local.md when you need a durable record of machine-specific context that should stay private, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CLAUDE.local.md to replace execution evidence, approval, or a record whose responsibility is outside machine-specific context that should stay private.
scoperequired — The paths, conditions, or boundary governed by this record for .claude/rules/.
rule contentrequired — Instructions that apply inside the declared scope for .claude/rules/.
Template .claude/rules/
# Rule: <area-name>
Applies to: `src/<area>/**`
- Preserve the public contract.
- Run the focused checks after changes.
- Do not edit unrelated files.
When to use
Use .claude/rules/ when you need a durable record of scoped rules close to the files they govern, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use .claude/rules/ to replace execution evidence, approval, or a record whose responsibility is outside scoped rules close to the files they govern.
Use settings.json when you need a durable record of shared Claude Code permissions and defaults, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use settings.json to replace execution evidence, approval, or a record whose responsibility is outside shared Claude Code permissions and defaults.
Version note Available keys and precedence should be checked against the current Claude Code documentation.
Use settings.local.json when you need a durable record of developer-local overrides outside the team contract, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use settings.local.json to replace execution evidence, approval, or a record whose responsibility is outside developer-local overrides outside the team contract.
allowed/review/approvalrequired — The allowed/review/approval recorded for this artifact for AI_CODING_POLICY.md.
data boundariesrequired — The data boundaries recorded for this artifact for AI_CODING_POLICY.md.
enforcement/ownerrequired — The enforcement/owner recorded for this artifact for AI_CODING_POLICY.md.
Template AI_CODING_POLICY.md
# AI coding policy
## Allowed
- <low-risk use>
## Review required
- <change or capability>
## Human approval required
- <production or destructive action>
## Data boundaries
- Never include secrets, PII, or customer data without approved controls.
## Enforcement
- <settings, hooks, gates, and owner>
When to use
Use AI_CODING_POLICY.md when you need a durable record of allowed AI use, review thresholds, and data boundaries, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use AI_CODING_POLICY.md to replace execution evidence, approval, or a record whose responsibility is outside allowed AI use, review thresholds, and data boundaries.
Use CODEOWNERS when you need a durable record of ownership rules for protected paths and review, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CODEOWNERS to replace execution evidence, approval, or a record whose responsibility is outside ownership rules for protected paths and review.
Use TASK_SPEC.md when you need a durable record of a verifiable contract for one bounded change, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use TASK_SPEC.md to replace execution evidence, approval, or a record whose responsibility is outside a verifiable contract for one bounded change.
shared expectationsrequired — The shared expectations recorded for this artifact for CAPSTONE_BRIEF.md.
guardrailsrequired — The guardrails recorded for this artifact for CAPSTONE_BRIEF.md.
Template CAPSTONE_BRIEF.md
# Capstone brief
## Shared expectations
- Deliver one complete core flow.
- Keep the scope reviewable.
## Guardrails
- No secrets in the repository.
- Record checks and remaining risks.
When to use
Use CAPSTONE_BRIEF.md when you need a durable record of shared expectations and guardrails for a capstone, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CAPSTONE_BRIEF.md to replace execution evidence, approval, or a record whose responsibility is outside shared expectations and guardrails for a capstone.
Defines how sequencing milestones around a priority user flow are captured for a bounded, reviewable engineering workflow.
Documented example
A reader-facing Backlog / roadmap record that keeps sequencing milestones around a priority user flow explicit for review.
Where it lives
project backlog or roadmap(repository; documented example)
Fields
milestonesrequired — The milestones recorded for this artifact for Backlog / roadmap.
core flowrequired — The core flow recorded for this artifact for Backlog / roadmap.
evaluationoptional — The evaluation recorded for this artifact for Backlog / roadmap.
Template Backlog / roadmap
# Roadmap
## Milestones
1. Discovery — map the current behavior.
2. Implementation — deliver the core flow.
3. Verification — run checks and prepare evidence.
## Evaluation
- <criterion for milestone completion>
When to use
Use Backlog / roadmap when you need a durable record of sequencing milestones around a priority user flow, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Backlog / roadmap to replace execution evidence, approval, or a record whose responsibility is outside sequencing milestones around a priority user flow.
Use CONTRACT.md when you need a durable record of interfaces, responsibilities, invariants, and failure behavior, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CONTRACT.md to replace execution evidence, approval, or a record whose responsibility is outside interfaces, responsibilities, invariants, and failure behavior.
goal/scoperequired — The goal/scope recorded for this artifact for REFACTORING_PLAN.md.
preserve/non-goalsrequired — The preserve/non-goals recorded for this artifact for REFACTORING_PLAN.md.
steps/checksrequired — The steps/checks recorded for this artifact for REFACTORING_PLAN.md.
stop/rollbackrequired — The stop/rollback recorded for this artifact for REFACTORING_PLAN.md.
Template REFACTORING_PLAN.md
# REFACTORING_PLAN.md
## Goal
<one structural improvement>
## Allowed scope
- <paths, symbols, or seam>
## Preserve
- <public behavior and invariants>
## Non-goals
- <feature, dependency, or unrelated cleanup>
## Steps
1. <inspect>
2. <change>
3. <check and review>
## Stop and rollback
- <condition and checkpoint>
When to use
Use REFACTORING_PLAN.md when you need a durable record of a behavior-preserving structural change plan, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use REFACTORING_PLAN.md to replace execution evidence, approval, or a record whose responsibility is outside a behavior-preserving structural change plan.
outcome/constraintsrequired — The outcome/constraints recorded for this artifact for MODERNIZATION_ROADMAP.md.
milestones/ownersrequired — The milestones/owners recorded for this artifact for MODERNIZATION_ROADMAP.md.
dependencies/evidence gatesrequired — The dependencies/evidence gates recorded for this artifact for MODERNIZATION_ROADMAP.md.
exit/rollback/risksrequired — The exit/rollback/risks recorded for this artifact for MODERNIZATION_ROADMAP.md.
Template MODERNIZATION_ROADMAP.md
# MODERNIZATION_ROADMAP.md
## Outcome and constraints
<why modernization matters and what is out of scope>
## Milestones
| Slice | Owner | Dependency | Evidence gate | Exit criteria | Rollback/hold |
| --- | --- | --- | --- | --- | --- |
| <slice> | <role> | <dependency> | <check> | <observable result> | <action> |
## Retirement plan
- <legacy removal condition>
## Open risks
- <risk and next decision>
When to use
Use MODERNIZATION_ROADMAP.md when you need a durable record of sequenced modernization slices and exit gates, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MODERNIZATION_ROADMAP.md to replace execution evidence, approval, or a record whose responsibility is outside sequenced modernization slices and exit gates.
Use MIGRATION_PLAN.md when you need a durable record of phased migration work with evidence gates and rollback, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MIGRATION_PLAN.md to replace execution evidence, approval, or a record whose responsibility is outside phased migration work with evidence gates and rollback.
scope/source-targetrequired — The scope/source-target recorded for this artifact for MIGRATION_TYPES.md.
classificationrequired — The classification recorded for this artifact for MIGRATION_TYPES.md.
evidence/owner/statusrequired — The evidence/owner/status recorded for this artifact for MIGRATION_TYPES.md.
ordering/stop conditionsrequired — The ordering/stop conditions recorded for this artifact for MIGRATION_TYPES.md.
Template MIGRATION_TYPES.md
# MIGRATION_TYPES.md
## Scope
- Source state: <current state>
- Target state: <target state>
- Boundary: <bounded initiative or pilot>
## Classification
| Work item | Type | Source -> target | Coupled with | Evidence gate | Owner | Status |
| --- | --- | --- | --- | --- | --- | --- |
| <item> | <code/dependency\|schema/data\|configuration\|infrastructure/platform\|operational> | <states> | <dependencies> | <check> | <role> | <Unknown/HOLD/ready> |
## Ordering and stop conditions
- <dependency or blocking unknown>
- <condition that stops the pilot>
When to use
Use MIGRATION_TYPES.md when you need a durable record of migration classification, ordering, and ownership, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MIGRATION_TYPES.md to replace execution evidence, approval, or a record whose responsibility is outside migration classification, ordering, and ownership.
representations/inventoryrequired — The representations/inventory recorded for this artifact for DATA_CONFIG_MIGRATION.md.
compatibility/sequencerequired — The compatibility/sequence recorded for this artifact for DATA_CONFIG_MIGRATION.md.
validationrequired — The validation recorded for this artifact for DATA_CONFIG_MIGRATION.md.
recovery/owner/statusrequired — The recovery/owner/status recorded for this artifact for DATA_CONFIG_MIGRATION.md.
secret boundaryrequired — The secret boundary recorded for this artifact for DATA_CONFIG_MIGRATION.md.
Template DATA_CONFIG_MIGRATION.md
# DATA_CONFIG_MIGRATION.md
## Scope and representations
- Data source -> target: <format/schema/state>
- Configuration source -> target: <keys/defaults/environments>
- Compatibility window: <coexistence period or Unknown>
## Plan
| Surface | Inventory | Sequence | Validation | Recovery | Owner | Status |
| --- | --- | --- | --- | --- | --- | --- |
| <schema/records/config/secrets references> | <items> | <ordered action> | <check> | <backout/forward-fix> | <role> | <Unknown/HOLD/ready> |
## Safety boundaries
- Never store secret values in this document.
- <irreversible action and explicit approval/stop condition>
When to use
Use DATA_CONFIG_MIGRATION.md when you need a durable record of representation changes, sequencing, integrity, and recovery, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use DATA_CONFIG_MIGRATION.md to replace execution evidence, approval, or a record whose responsibility is outside representation changes, sequencing, integrity, and recovery.
user/problemrequired — The user/problem recorded for this artifact for VALUE_PROPOSITION.md.
alternative/outcomerequired — The alternative/outcome recorded for this artifact for VALUE_PROPOSITION.md.
differentiationrequired — The differentiation recorded for this artifact for VALUE_PROPOSITION.md.
proof signalrequired — The proof signal recorded for this artifact for VALUE_PROPOSITION.md.
assumptions/statusrequired — The assumptions/status recorded for this artifact for VALUE_PROPOSITION.md.
Template VALUE_PROPOSITION.md
# VALUE_PROPOSITION.md
## User and problem
- User: <primary user>
- Problem: <recurring loss or friction>
## Promise
- Alternative: <how the user solves it today>
- Outcome: <observable improvement>
- Differentiation: <why this approach may help>
## Proof boundary
- Signal: <metric or observation>
- Assumptions: <assumptions to validate>
- Status: documented example; user validation is Unknown.
When to use
Use VALUE_PROPOSITION.md when you need a durable record of user problem, promised outcome, and proof signal, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use VALUE_PROPOSITION.md to replace execution evidence, approval, or a record whose responsibility is outside user problem, promised outcome, and proof signal.
user/contextrequired — The user/context recorded for this artifact for USER_JTBD.md.
job/outcomerequired — The job/outcome recorded for this artifact for USER_JTBD.md.
pains/gainsrequired — The pains/gains recorded for this artifact for USER_JTBD.md.
constraintsrequired — Technical, time, policy, or data limits for USER_JTBD.md.
assumptionsrequired — The assumptions recorded for this artifact for USER_JTBD.md.
Template USER_JTBD.md
# USER_JTBD.md
## Situation
- User: <specific role>
- Trigger/context: <when this job appears>
## Job
- When <situation>, I want to <job>, so I can <desired outcome>.
## Constraints
- Pains: <friction>
- Gains: <desired progress>
- Constraints: <time, access, policy or quality limits>
## Validation boundary
- Assumptions: <what still needs research>
- Status: documented example; observed user behavior is Unknown.
When to use
Use USER_JTBD.md when you need a durable record of user context, desired progress, pains, gains, and constraints, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use USER_JTBD.md to replace execution evidence, approval, or a record whose responsibility is outside user context, desired progress, pains, gains, and constraints.
definition/unitrequired — The definition/unit recorded for this artifact for SUCCESS_METRIC.md.
baseline/target/windowrequired — The baseline/target/window recorded for this artifact for SUCCESS_METRIC.md.
collection methodrequired — The collection method recorded for this artifact for SUCCESS_METRIC.md.
guardrailrequired — The guardrail recorded for this artifact for SUCCESS_METRIC.md.
interpretation limitsrequired — The interpretation limits recorded for this artifact for SUCCESS_METRIC.md.
Template SUCCESS_METRIC.md
# SUCCESS_METRIC.md
## Metric
- Name: <metric name and unit>
- Definition: <what counts and what does not>
- Baseline: <known baseline or Unknown>
- Target: <bounded target>
- Window: <observation period>
## Method and guardrails
- Collection: <how the signal would be observed>
- Leading signal: <flow completion or quality signal>
- Guardrail: <quality, safety or rework constraint>
- Limits: <what this metric cannot prove>
- Status: documented example; no measured outcome is claimed.
When to use
Use SUCCESS_METRIC.md when you need a durable record of a measurable outcome with baseline, target, and limits, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use SUCCESS_METRIC.md to replace execution evidence, approval, or a record whose responsibility is outside a measurable outcome with baseline, target, and limits.
Use RELEASE_SLICE.md when you need a durable record of the smallest coherent flow ready for review, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use RELEASE_SLICE.md to replace execution evidence, approval, or a record whose responsibility is outside the smallest coherent flow ready for review.
dimensionsrequired — The dimensions recorded for this artifact for CAPSTONE_RUBRIC.md.
signals/evidencerequired — The signals/evidence recorded for this artifact for CAPSTONE_RUBRIC.md.
scale/weightrequired — The scale/weight recorded for this artifact for CAPSTONE_RUBRIC.md.
decision boundaryrequired — The decision boundary recorded for this artifact for CAPSTONE_RUBRIC.md.
Template CAPSTONE_RUBRIC.md
# CAPSTONE_RUBRIC.md
Dimension: <problem / flow / scope / verification / evidence / communication>
Expected signal: <observable criterion>
Evidence required: <file, command or demo anchor>
Status scale: <not shown / partial / shown / needs verification>
Weight: <agreed value or Unknown>
Reviewer note: <feedback or Unknown>
Decision boundary: <GO / HOLD / remediation>
Status: documented example; rubric application and score: Unknown.
When to use
Use CAPSTONE_RUBRIC.md when you need a durable record of evaluation dimensions, evidence anchors, and decision boundaries, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CAPSTONE_RUBRIC.md to replace execution evidence, approval, or a record whose responsibility is outside evaluation dimensions, evidence anchors, and decision boundaries.
role and sourcerequired — Vacancy, source, and URL or Unknown.
requirements and statusrequired — Atomic requirements with Fit, Partial, Gap, or Unknown status.
evidence and confidencerequired — Evidence source and confidence level.
next checks and boundaryrequired — Clarifications and external-evaluation boundary.
Template JOB_FIT_GAP_MAP.md
# JOB_FIT_GAP_MAP.md\n\nRole/source: <vacancy and URL or Unknown>\n\n| Requirement | Status | Evidence | Confidence | Next check |\n| --- | --- | --- | --- | --- |\n| <must-have> | Fit / Partial / Gap / Unknown | <source or Unknown> | <high/medium/low> | <bounded action> |\n\nBoundary: this map is not an external assessment and does not prove hiring fit.\nStatus: documented example.\n
When to use
Use JOB_FIT_GAP_MAP.md to analyze vacancy requirements safely and choose the next check.
When it is a poor choice
Do not use it for automatic rejection or approval, an invented candidate score, or a replacement for human assessment.
Defines how facts, decisions, checks, and residual uncertainty are captured for a bounded, reviewable engineering workflow.
Name or path variant
A reader-facing EVIDENCE.md record that keeps facts, decisions, checks, and residual uncertainty explicit for review.
Where it lives
EVIDENCE.md(repository; present in repository)
docs/EVIDENCE.md(repository; name or path variant)
Fields
assignment/resultrequired — What was checked and what the evidence showed for EVIDENCE.md.
decisionsrequired — Decisions made and the reasoning behind them for EVIDENCE.md.
verificationrequired — The planned check and its expected signal for EVIDENCE.md.
risks/open questionsoptional — Unknowns, risks, and decisions still requiring attention for EVIDENCE.md.
Template EVIDENCE.md
# Evidence
## Result
<what was checked and what happened>
## Decisions
- <decision and rationale>
## Verification
- `<command>` — <result>
## Open risks
- <unresolved item or none>
When to use
Use EVIDENCE.md when you need a durable record of facts, decisions, checks, and residual uncertainty, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use EVIDENCE.md to replace execution evidence, approval, or a record whose responsibility is outside facts, decisions, checks, and residual uncertainty.
Aliases and variants
EVIDENCE_LOG.md · docs/EVIDENCE.md
Version note EVIDENCE_LOG.md is used in the learning materials as a legacy or conceptual variant; agree on the canonical filename before adopting it.
goal/scoperequired — The goal/scope recorded for this artifact for HANDOFF_NOTE.md.
changed filesrequired — Files changed or inspected for HANDOFF_NOTE.md.
decisions/assumptionsrequired — Decisions and assumptions that shape the handoff for HANDOFF_NOTE.md.
evidence/checksrequired — Commands and observed verification results for HANDOFF_NOTE.md.
risks/next steprequired — Risks and the one next action for HANDOFF_NOTE.md.
Template HANDOFF_NOTE.md
# Handoff note
## Goal and scope
<what this work covers>
## Changed files
- `<path>` — <change>
## Decisions
- <decision>
## Checks
- `<command>` — <result>
## Next step
<one concrete next action>
When to use
Use HANDOFF_NOTE.md when you need a durable record of context transfer at a milestone boundary, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use HANDOFF_NOTE.md to replace execution evidence, approval, or a record whose responsibility is outside context transfer at a milestone boundary.
Use PR description when you need a durable record of review context, checks, risks, and requested attention, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use PR description to replace execution evidence, approval, or a record whose responsibility is outside review context, checks, risks, and requested attention.
Defines how the intent and boundary of one history entry are captured for a bounded, reviewable engineering workflow.
Operational or external artifact
A reader-facing Commit message record that keeps the intent and boundary of one history entry explicit for review.
Where it lives
Git commit metadata(generated; operational or external artifact)
Fields
intentrequired — The intent recorded for this artifact for Commit message.
scoperequired — The paths, conditions, or boundary governed by this record for Commit message.
Template Commit message
<type>(<scope>): <short imperative summary>
Explain why the change is needed and mention verification when useful.
When to use
Use Commit message when you need a durable record of the intent and boundary of one history entry, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Commit message to replace execution evidence, approval, or a record whose responsibility is outside the intent and boundary of one history entry.
Use Changelog when you need a durable record of user-visible change history and transition notes, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Changelog to replace execution evidence, approval, or a record whose responsibility is outside user-visible change history and transition notes.
Use HANDOFF_REVIEW.md when you need a durable record of an independent review of source, findings, and next decision, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use HANDOFF_REVIEW.md to replace execution evidence, approval, or a record whose responsibility is outside an independent review of source, findings, and next decision.
impact/timelinerequired — The impact/timeline recorded for this artifact for Postmortem.
cause/controlsrequired — The cause/controls recorded for this artifact for Postmortem.
actions/verificationrequired — The actions/verification recorded for this artifact for Postmortem.
Template Postmortem
# Postmortem: <incident or failure>
## Impact
<observable impact and duration>
## Timeline
- <time> — <event>
## Root cause and contributing factors
- <verified cause>
## What worked / failed
- <control> — <result>
## Actions
- [ ] <owner> — <preventive or corrective action>
## Verification
- <how the fix will be checked>
When to use
Use Postmortem when you need a durable record of impact, causes, controls, and corrective actions, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Postmortem to replace execution evidence, approval, or a record whose responsibility is outside impact, causes, controls, and corrective actions.
Use REVIEW_NOTES.md when you need a durable record of findings, checks, questions, and a cautious verdict, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use REVIEW_NOTES.md to replace execution evidence, approval, or a record whose responsibility is outside findings, checks, questions, and a cautious verdict.
Defines how repeatable delivery steps and their observed limits are captured for a bounded, reviewable engineering workflow.
Present in repository
A reader-facing RUNBOOK.md record that keeps repeatable delivery steps and their observed limits explicit for review.
Where it lives
RUNBOOK.md(repository; present in repository)
Fields
task/daterequired — The task/date recorded for this artifact for RUNBOOK.md.
statusrequired — The status recorded for this artifact for RUNBOOK.md.
scope/filesrequired — The scope/files recorded for this artifact for RUNBOOK.md.
resultrequired — The result recorded for this artifact for RUNBOOK.md.
verification/limitationsrequired — The verification/limitations recorded for this artifact for RUNBOOK.md.
Template RUNBOOK.md
# Project delivery runbook
**Last updated:** <YYYY-MM-DD>
## Task log
### <task name> — `<implemented|reviewed|partially verified|not performed>`
- Goal and scope: <what was requested>
- Changed or reviewed files: `<paths>`
- Result: <confirmed outcome>
- Verification: `<command or manual check>` — <actual result>
- Limitations: <known gap or none>
## Open limitations
- <unverified item or none>
When to use
Use RUNBOOK.md when you need a durable record of repeatable delivery steps and their observed limits, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use RUNBOOK.md to replace execution evidence, approval, or a record whose responsibility is outside repeatable delivery steps and their observed limits.
Use MODERNIZATION_ANTI_PATTERNS.md when you need a durable record of unsafe modernization habits and safer alternatives, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MODERNIZATION_ANTI_PATTERNS.md to replace execution evidence, approval, or a record whose responsibility is outside unsafe modernization habits and safer alternatives.
Use MIGRATION_VALIDATION_REPORT.md when you need a durable record of expected versus observed migration behavior, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MIGRATION_VALIDATION_REPORT.md to replace execution evidence, approval, or a record whose responsibility is outside expected versus observed migration behavior.
scope/checkpoint/decisionrequired — The scope/checkpoint/decision recorded for this artifact for POST_MIGRATION_NOTES.md.
expected/observed signalsrequired — The expected/observed signals recorded for this artifact for POST_MIGRATION_NOTES.md.
evidence/discrepanciesrequired — The evidence/discrepancies recorded for this artifact for POST_MIGRATION_NOTES.md.
residual risks/follow-uprequired — The residual risks/follow-up recorded for this artifact for POST_MIGRATION_NOTES.md.
handoff/lessonsrequired — The handoff/lessons recorded for this artifact for POST_MIGRATION_NOTES.md.
Template POST_MIGRATION_NOTES.md
# POST_MIGRATION_NOTES.md
## Scope and decision
- Migration slice/checkpoint: <bounded surface>
- Switch decision: <GO | HOLD | NARROW | ROLLBACK>
- Observation window: <window or Unknown>
## Observations
| Signal | Expected | Observed | Evidence | Status |
| --- | --- | --- | --- | --- |
| representative behavior | <contract> | <observation> | <anchor> | <pass/fail/Unknown> |
| data/configuration state | <invariant> | <observation> | <anchor> | <pass/fail/Unknown> |
| operational signal | <threshold> | <observation> | <anchor> | <pass/fail/Unknown> |
## Follow-up and handoff
- Residual risk: <risk or Unknown>
- Next action: <bounded action>
- Owner: <role>
- Lessons learned: <observation>
- Never store secret values here.
- Status: documented example; no post-migration outcome is claimed.
When to use
Use POST_MIGRATION_NOTES.md when you need a durable record of the decision record after a migration checkpoint, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use POST_MIGRATION_NOTES.md to replace execution evidence, approval, or a record whose responsibility is outside the decision record after a migration checkpoint.
Use CODEBASE_INVENTORY.md when you need a durable record of a compact map of repository structure and risk, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CODEBASE_INVENTORY.md to replace execution evidence, approval, or a record whose responsibility is outside a compact map of repository structure and risk.
Use API_MAP.md when you need a durable record of traceability across routes, handlers, and integration boundaries, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use API_MAP.md to replace execution evidence, approval, or a record whose responsibility is outside traceability across routes, handlers, and integration boundaries.
contextrequired — The context recorded for this artifact for CLAWD Wisdom.
evidencerequired — The evidence recorded for this artifact for CLAWD Wisdom.
limitationrequired — The limitation recorded for this artifact for CLAWD Wisdom.
Template CLAWD Wisdom
# CLAWD Wisdom
## <lesson>
- Context: <where this applies>
- Evidence: <file, command, or source>
- Insight: <verified reusable conclusion>
- Limitation: <where it does not apply>
- Reviewed: <date or version>
When to use
Use CLAWD Wisdom when you need a durable record of contextual advice tied to evidence and limitations, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CLAWD Wisdom to replace execution evidence, approval, or a record whose responsibility is outside contextual advice tied to evidence and limitations.
Use research-digest.md when you need a durable record of a research question, source trail, and bounded recommendation, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use research-digest.md to replace execution evidence, approval, or a record whose responsibility is outside a research question, source trail, and bounded recommendation.
scope/daterequired — The scope/date recorded for this artifact for DEBT_SIGNALS.md.
area/evidencerequired — The area/evidence recorded for this artifact for DEBT_SIGNALS.md.
riskrequired — The risk recorded for this artifact for DEBT_SIGNALS.md.
next step/limitationrequired — The next step/limitation recorded for this artifact for DEBT_SIGNALS.md.
Template DEBT_SIGNALS.md
# DEBT_SIGNALS.md
## Scope and date
- Area: <module or flow>
- Reviewed: <date or revision>
## Signals
| Area | Evidence | Risk | Next step |
| --- | --- | --- | --- |
| <area> | <path, command, report, or commit> | <possible impact> | <one concrete check> |
## Limitations
- A signal is an indicator, not proof of a defect.
When to use
Use DEBT_SIGNALS.md when you need a durable record of observable indicators of legacy risk, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use DEBT_SIGNALS.md to replace execution evidence, approval, or a record whose responsibility is outside observable indicators of legacy risk.
Use RISK_MAP.md when you need a durable record of criticality, change risk, evidence gaps, and action, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use RISK_MAP.md to replace execution evidence, approval, or a record whose responsibility is outside criticality, change risk, evidence gaps, and action.
purpose/revisionrequired — The purpose/revision recorded for this artifact for ARCHITECTURE_CURRENT.md.
subsystems/flowsrequired — The subsystems/flows recorded for this artifact for ARCHITECTURE_CURRENT.md.
facts/assumptionsrequired — The facts/assumptions recorded for this artifact for ARCHITECTURE_CURRENT.md.
manual checks/discrepanciesrequired — The manual checks/discrepancies recorded for this artifact for ARCHITECTURE_CURRENT.md.
Template ARCHITECTURE_CURRENT.md
# ARCHITECTURE_CURRENT.md
## Document purpose
<actual current behavior, not desired architecture>
## Subsystems
## Critical flows
## Confirmed facts
## Assumptions
## Manual checks needed
## Differences from historical documentation
When to use
Use ARCHITECTURE_CURRENT.md when you need a durable record of confirmed architecture facts and unresolved discrepancies, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use ARCHITECTURE_CURRENT.md to replace execution evidence, approval, or a record whose responsibility is outside confirmed architecture facts and unresolved discrepancies.
Use BEHAVIOR_INVENTORY.md when you need a durable record of current observable behavior and characterization candidates, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use BEHAVIOR_INVENTORY.md to replace execution evidence, approval, or a record whose responsibility is outside current observable behavior and characterization candidates.
Use CRITICAL_FLOWS.md when you need a durable record of business-critical runtime paths and failure handling, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CRITICAL_FLOWS.md to replace execution evidence, approval, or a record whose responsibility is outside business-critical runtime paths and failure handling.
module/pathrequired — The module/path recorded for this artifact for MODULE_INVENTORY.md.
responsibility/entry pointsrequired — The responsibility/entry points recorded for this artifact for MODULE_INVENTORY.md.
dependencies/testsrequired — The dependencies/tests recorded for this artifact for MODULE_INVENTORY.md.
owner/risksrequired — The owner/risks recorded for this artifact for MODULE_INVENTORY.md.
evidencerequired — The evidence recorded for this artifact for MODULE_INVENTORY.md.
Template MODULE_INVENTORY.md
# MODULE_INVENTORY.md
## Module: <name>
- Path: <path>
- Responsibility: <observed responsibility>
- Entry points: <symbols or routes>
- Dependencies: <internal and external>
- Tests: <paths and coverage signal>
- Owner: <confirmed or inferred>
- Risks and unknowns: <items>
- Evidence: <anchors>
When to use
Use MODULE_INVENTORY.md when you need a durable record of module boundaries, entry points, dependencies, and risks, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MODULE_INVENTORY.md to replace execution evidence, approval, or a record whose responsibility is outside module boundaries, entry points, dependencies, and risks.
scope/revisionrequired — The scope/revision recorded for this artifact for MODERNIZATION_BASELINE.md.
observable behaviorrequired — The observable behavior recorded for this artifact for MODERNIZATION_BASELINE.md.
invariantsrequired — The invariants recorded for this artifact for MODERNIZATION_BASELINE.md.
checks/rollbackrequired — The checks/rollback recorded for this artifact for MODERNIZATION_BASELINE.md.
Template MODERNIZATION_BASELINE.md
# MODERNIZATION_BASELINE.md
## Scope and revision
- Module/flow: <area>
- Revision: <commit or date>
## Observable behavior
- Inputs: <inputs>
- Outputs: <outputs>
- Side effects: <effects>
- Failure paths: <errors and recovery>
## Invariants
- <contract that must remain true>
## Checks and observability
- `<command or scenario>` — <actual result>
## Rollback point and unknowns
- Checkpoint: <reference>
- Unknowns: <items>
When to use
Use MODERNIZATION_BASELINE.md when you need a durable record of a behavior baseline for a safe modernization slice, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MODERNIZATION_BASELINE.md to replace execution evidence, approval, or a record whose responsibility is outside a behavior baseline for a safe modernization slice.
flow/current pathrequired — The flow/current path recorded for this artifact for SEAM_MAP.md.
candidate seamrequired — The candidate seam recorded for this artifact for SEAM_MAP.md.
dependency/test directionrequired — The dependency/test direction recorded for this artifact for SEAM_MAP.md.
risk/next checkrequired — The risk/next check recorded for this artifact for SEAM_MAP.md.
Template SEAM_MAP.md
# SEAM_MAP.md
## Flow and boundary
- Flow: <business or runtime flow>
- Entry point: <caller>
## Current path
- Caller: <component>
- Legacy callee: <component>
- Side effects: <effects>
## Candidate seam
- Interface/adapter/event/routing: <boundary>
- Dependency direction: <producer -> consumer>
- Test seam: <how to observe it>
## Migration risk and next slice
- Risk: <risk>
- Next check: <one verification>
When to use
Use SEAM_MAP.md when you need a durable record of candidate boundaries where dependencies can be controlled, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use SEAM_MAP.md to replace execution evidence, approval, or a record whose responsibility is outside candidate boundaries where dependencies can be controlled.
source/target scoperequired — The source/target scope recorded for this artifact for MIGRATION_DISCOVERY.md.
evidencerequired — The evidence recorded for this artifact for MIGRATION_DISCOVERY.md.
knowns/assumptions/unknownsrequired — The knowns/assumptions/unknowns recorded for this artifact for MIGRATION_DISCOVERY.md.
starting checkpointrequired — The starting checkpoint recorded for this artifact for MIGRATION_DISCOVERY.md.
stop conditionsrequired — The stop conditions recorded for this artifact for MIGRATION_DISCOVERY.md.
Template MIGRATION_DISCOVERY.md
# MIGRATION_DISCOVERY.md
## Source and target
- Source state: <runtime, framework, platform, or version>
- Target state: <runtime, framework, platform, or version>
- Migration slice: <bounded area>
## Evidence
- <repository, build, deployment, integration or official-doc anchor>
## Known, assumed, unknown
- Known: <confirmed fact>
- Assumption: <assumption and owner>
- Unknown: <question and next check>
## Starting checkpoint
- Revision/environment: <reference>
- Baseline check: <command or scenario>
## Stop conditions
- <condition that blocks analysis or pilot>
When to use
Use MIGRATION_DISCOVERY.md when you need a durable record of source state, target intent, and migration unknowns, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MIGRATION_DISCOVERY.md to replace execution evidence, approval, or a record whose responsibility is outside source state, target intent, and migration unknowns.
version windowrequired — The version window recorded for this artifact for CHANGELOG_RESEARCH.md.
official evidencerequired — The official evidence recorded for this artifact for CHANGELOG_RESEARCH.md.
change and impactrequired — The change and impact recorded for this artifact for CHANGELOG_RESEARCH.md.
confidence/next checkrequired — The confidence/next check recorded for this artifact for CHANGELOG_RESEARCH.md.
limitsrequired — The limits recorded for this artifact for CHANGELOG_RESEARCH.md.
Template CHANGELOG_RESEARCH.md
# CHANGELOG_RESEARCH.md
## Version window
- Source: <version>
- Target: <version>
## Findings
| Version | Official section | Change type | Affected area | Impact | Confidence | Next check |
| --- | --- | --- | --- | --- | --- | --- |
| <version> | <URL or section> | <breaking/deprecated/behavior/config> | <path or component> | <possible impact> | <confirmed/needs verification/Unknown> | <check> |
## Limits
- <release or repository fact not verified>
When to use
Use CHANGELOG_RESEARCH.md when you need a durable record of official release changes and their possible impact, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CHANGELOG_RESEARCH.md to replace execution evidence, approval, or a record whose responsibility is outside official release changes and their possible impact.
nodes/source-targetrequired — The nodes/source-target recorded for this artifact for DEPENDENCY_GRAPH.md.
directed edgesrequired — The directed edges recorded for this artifact for DEPENDENCY_GRAPH.md.
affected flowsrequired — The affected flows recorded for this artifact for DEPENDENCY_GRAPH.md.
evidence/unknownsrequired — The evidence/unknowns recorded for this artifact for DEPENDENCY_GRAPH.md.
Template DEPENDENCY_GRAPH.md
# DEPENDENCY_GRAPH.md
## Nodes
| Node | Source | Target | Type | Evidence |
| --- | --- | --- | --- | --- |
| <component> | <source state> | <target state> | <runtime/framework/plugin/integration> | <anchor> |
## Directed edges
- <producer> -> <consumer>: <contract or version constraint>
## Affected flows
- <flow>: <entry point, path and side effects>
## Hubs and unknowns
- High-impact hub: <node and reason>
- Unknown: <edge or constraint and next check>
When to use
Use DEPENDENCY_GRAPH.md when you need a durable record of directed dependency relationships and affected flows, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use DEPENDENCY_GRAPH.md to replace execution evidence, approval, or a record whose responsibility is outside directed dependency relationships and affected flows.
source/target scoperequired — The source/target scope recorded for this artifact for COMPATIBILITY_MATRIX.md.
technical dimensionsrequired — The technical dimensions recorded for this artifact for COMPATIBILITY_MATRIX.md.
status/evidencerequired — The status/evidence recorded for this artifact for COMPATIBILITY_MATRIX.md.
owner/next actionrequired — The owner/next action recorded for this artifact for COMPATIBILITY_MATRIX.md.
Template COMPATIBILITY_MATRIX.md
# COMPATIBILITY_MATRIX.md
## Scope
- Source: <version or platform>
- Target: <version or platform>
## Decisions
| Component/edge | API | Config | ABI | Runtime | Data format | Protocol | Operations | Status | Evidence | Owner |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| <item> | <status> | <status> | <status> | <status> | <status> | <status> | <status> | <compatible/blocking/Unknown> | <anchor> | <role> |
## Blocking and unknown items
- <item> — <next check or hold decision>
When to use
Use COMPATIBILITY_MATRIX.md when you need a durable record of source-to-target compatibility decisions by dimension, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use COMPATIBILITY_MATRIX.md to replace execution evidence, approval, or a record whose responsibility is outside source-to-target compatibility decisions by dimension.
namerequired — The stable identifier of this workflow or role for SKILL.md. Example: issue-analysis
descriptionrequired — The trigger, responsibility, and result of the workflow for SKILL.md.
argument-hintoptional — The expected slash-command arguments for SKILL.md. Example: [input-path] [focus]
when_to_useconventional — The conditions that justify running the workflow for SKILL.md.
allowed_toolsconventional — The minimum tools needed for the workflow for SKILL.md. Example: read, grep
instructions/templatesrequired — The main procedure and reusable templates for SKILL.md.
Template SKILL.md
---
name: <skill-name>
description: <what this workflow does>
argument-hint: "[input-path] [focus]"
---
# <Skill title>
## When to use
Use when <trigger>.
## Steps
1. Inspect the input.
2. Perform the focused workflow.
3. Return evidence and remaining risks.
## Constraints
- Do not modify files outside the declared scope.
When to use
Use SKILL.md when you need a durable record of a repeatable procedure with a stable trigger, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use SKILL.md to replace execution evidence, approval, or a record whose responsibility is outside a repeatable procedure with a stable trigger.
Version note The fields in this TASK_SPEC example are project conventions; exact frontmatter depends on the current Claude Code version.
namerequired — The stable identifier of this workflow or role for Custom subagent.
descriptionrequired — The trigger, responsibility, and result of the workflow for Custom subagent.
toolsconventional — Tools permitted for this role for Custom subagent.
role/prohibitionsrequired — Role boundaries and actions that are prohibited for Custom subagent.
result formatrequired — The evidence-backed shape of the returned findings for Custom subagent.
Template Custom subagent
---
name: <reviewer>
description: Reviews <area> and returns evidence-backed findings.
tools: Read, Grep
---
# Role
Inspect only the assigned scope.
# Output
- Finding
- File and line
- Evidence
- Confidence
# Prohibitions
Do not edit files or broaden the scope.
When to use
Use Custom subagent when you need a durable record of a constrained role for focused discovery or review, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Custom subagent to replace execution evidence, approval, or a record whose responsibility is outside a constrained role for focused discovery or review.
Use Hook configuration when you need a durable record of event-driven local automation with an escape hatch, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Hook configuration to replace execution evidence, approval, or a record whose responsibility is outside event-driven local automation with an escape hatch.
Version note Event names and matcher syntax should be checked against the current CLI documentation.
Use Plugin when you need a durable record of a packaged Claude Code extension and its permissions, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Plugin to replace execution evidence, approval, or a record whose responsibility is outside a packaged Claude Code extension and its permissions.
workflowrequired — The workflow recorded for this artifact for commands.md.
run contextrequired — The run context recorded for this artifact for commands.md.
expected resultrequired — The expected result recorded for this artifact for commands.md.
Template commands.md
# Commands
## <workflow>
- Purpose: <what it verifies or changes>
- Run from: <directory>
- Command: `<command>`
- Expected result: <observable output>
- Stop if: <failure or unsafe condition>
When to use
Use commands.md when you need a durable record of a runnable command catalog with expected signals, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use commands.md to replace execution evidence, approval, or a record whose responsibility is outside a runnable command catalog with expected signals.
allowed scoperequired — The allowed scope recorded for this artifact for CLAWD YOLO.
guardrailsrequired — The guardrails recorded for this artifact for CLAWD YOLO.
human checkpointrequired — The human checkpoint recorded for this artifact for CLAWD YOLO.
Template CLAWD YOLO
# CLAWD YOLO
## Allowed scope
- Paths: <narrow paths>
- Actions: <allowed actions>
## Guardrails
- No secrets or destructive operations.
- Stop on: <failure signal>
- Human checkpoint: <before merge or release>
When to use
Use CLAWD YOLO when you need a durable record of a deliberately narrow high-autonomy permission boundary, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CLAWD YOLO to replace execution evidence, approval, or a record whose responsibility is outside a deliberately narrow high-autonomy permission boundary.
trigger/inputsrequired — The trigger/inputs recorded for this artifact for workflow.md.
stages/ownersrequired — The stages/owners recorded for this artifact for workflow.md.
evidence/failure pathrequired — The evidence/failure path recorded for this artifact for workflow.md.
Template workflow.md
# Workflow: <name>
## Trigger
<when to use>
## Inputs
- <input>
## Stages
1. <stage and owner>
2. <stage and owner>
## Evidence
- <output artifact>
## Failure path
<how to stop, retry, rollback, or escalate>
When to use
Use workflow.md when you need a durable record of stages, owners, inputs, and failure handling, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use workflow.md to replace execution evidence, approval, or a record whose responsibility is outside stages, owners, inputs, and failure handling.
Use MCP when you need a durable record of the connection, scope, and health contract for an MCP server, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use MCP to replace execution evidence, approval, or a record whose responsibility is outside the connection, scope, and health contract for an MCP server.
Version note The concrete configuration is version-sensitive.
Defines how the branch, worktree, and diff state under review are captured for a bounded, reviewable engineering workflow.
Operational or external artifact
A reader-facing Git branch / worktree / diff record that keeps the branch, worktree, and diff state under review explicit for review.
Where it lives
.git/(generated; operational or external artifact)
worktree/(generated; operational or external artifact)
working diff(generated; operational or external artifact)
Fields
baselinerequired — The baseline recorded for this artifact for Git branch / worktree / diff.
scoperequired — The paths, conditions, or boundary governed by this record for Git branch / worktree / diff.
diffrequired — The diff recorded for this artifact for Git branch / worktree / diff.
checkpointoptional — The checkpoint recorded for this artifact for Git branch / worktree / diff.
Template Git branch / worktree / diff
git switch -c <branch-name>
git status
git diff -- <path>
# Review the diff, run checks, then create a checkpoint.
When to use
Use Git branch / worktree / diff when you need a durable record of the branch, worktree, and diff state under review, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Git branch / worktree / diff to replace execution evidence, approval, or a record whose responsibility is outside the branch, worktree, and diff state under review.
Use CLAWD Runner when you need a durable record of the input, environment, and outcome of an automated run, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CLAWD Runner to replace execution evidence, approval, or a record whose responsibility is outside the input, environment, and outcome of an automated run.
Use locales.json when you need a durable record of supported locales and fallback namespace configuration, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use locales.json to replace execution evidence, approval, or a record whose responsibility is outside supported locales and fallback namespace configuration.
Use Locale API/UI/test bundle when you need a durable record of locale keys across API, UI, and test layers, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use Locale API/UI/test bundle to replace execution evidence, approval, or a record whose responsibility is outside locale keys across API, UI, and test layers.
Use run-status.yaml when you need a durable record of machine-readable lifecycle state and stage evidence, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use run-status.yaml to replace execution evidence, approval, or a record whose responsibility is outside machine-readable lifecycle state and stage evidence.
Use diagnosis.json when you need a durable record of a compact status classification with confidence and next action, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use diagnosis.json to replace execution evidence, approval, or a record whose responsibility is outside a compact status classification with confidence and next action.
scope/baselinerequired — The scope/baseline recorded for this artifact for CHARACTERIZATION_TESTS.md.
cases/inputsrequired — The cases/inputs recorded for this artifact for CHARACTERIZATION_TESTS.md.
observable outputs/side effectsrequired — The observable outputs/side effects recorded for this artifact for CHARACTERIZATION_TESTS.md.
invariants/evidencerequired — The invariants/evidence recorded for this artifact for CHARACTERIZATION_TESTS.md.
run/limitsrequired — The run/limits recorded for this artifact for CHARACTERIZATION_TESTS.md.
Template CHARACTERIZATION_TESTS.md
# CHARACTERIZATION_TESTS.md
## Scope and baseline
- Module/flow: <area>
- Revision: <commit or date>
- Behavior under test: <observable contract>
## Cases
| Case | Inputs | Expected observable output | Side effects | Evidence |
| --- | --- | --- | --- | --- |
| <case> | <reproducible input> | <status, value, event, or error> | <effect or none> | <test/log/source> |
## Invariants
- <behavior that must remain unchanged>
## Run and interpretation
- Command: `<focused test command>`
- Baseline result: <actual result>
- Stop if: <unexpected behavior or missing evidence>
## Limits
- <unknown behavior or scenario not covered>
When to use
Use CHARACTERIZATION_TESTS.md when you need a durable record of baseline cases and observable behavior before change, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CHARACTERIZATION_TESTS.md to replace execution evidence, approval, or a record whose responsibility is outside baseline cases and observable behavior before change.
fragment/pathsrequired — The fragment/paths recorded for this artifact for STRANGLER_SLICE.md.
routing/compatibilityrequired — The routing/compatibility recorded for this artifact for STRANGLER_SLICE.md.
side effects/observabilityrequired — The side effects/observability recorded for this artifact for STRANGLER_SLICE.md.
rollback/retirementrequired — The rollback/retirement recorded for this artifact for STRANGLER_SLICE.md.
Template STRANGLER_SLICE.md
# STRANGLER_SLICE.md
## Fragment and boundary
<bounded behavior being replaced>
## Paths
- Legacy: <old path>
- New: <new path>
- Router: <explicit selection rule>
## Compatibility and side effects
- Contract: <preserved behavior>
- Side effects: <single-write/idempotency rule>
- Observability: <signals>
## Rollout and rollback
- Rollout: <small expansion>
- Rollback: <switch and state recovery>
## Retirement criteria
- <evidence required before removing legacy>
When to use
Use STRANGLER_SLICE.md when you need a durable record of an incremental legacy/new coexistence boundary, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use STRANGLER_SLICE.md to replace execution evidence, approval, or a record whose responsibility is outside an incremental legacy/new coexistence boundary.
scope/checkpoint/triggerrequired — The scope/checkpoint/trigger recorded for this artifact for ROLLBACK.md.
owner/escalationrequired — The owner/escalation recorded for this artifact for ROLLBACK.md.
ordered recoveryrequired — The ordered recovery recorded for this artifact for ROLLBACK.md.
backout/forward-fix boundaryrequired — The backout/forward-fix boundary recorded for this artifact for ROLLBACK.md.
post-rollback verificationrequired — The post-rollback verification recorded for this artifact for ROLLBACK.md.
Template ROLLBACK.md
# ROLLBACK.md
## Boundary
- Scope: <bounded pilot>
- Checkpoint: <source revision/config/state checkpoint>
- Trigger: <observable threshold or blocking discrepancy>
- Owner: <role>
## Ordered recovery
1. <route traffic or stop the affected slice>
2. <restore code or artifact>
3. <restore compatible configuration>
4. <backout data/schema or choose forward-fix>
5. <verify representative behavior and invariants>
## Decision
- State recovery: <verified/Unknown>
- Decision: <GO | HOLD | ROLLBACK>
- Never store secret values here.
- Status: documented example; no recovery was executed.
When to use
Use ROLLBACK.md when you need a durable record of recoverable triggers, ordered actions, and post-recovery checks, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use ROLLBACK.md to replace execution evidence, approval, or a record whose responsibility is outside recoverable triggers, ordered actions, and post-recovery checks.
Defines how orientation, setup, and current project status are captured for a bounded, reviewable engineering workflow.
Present in repository
A reader-facing README.md record that keeps orientation, setup, and current project status explicit for review.
Where it lives
README.md(repository; present in repository)
Fields
setuprequired — The setup recorded for this artifact for README.md.
scoperequired — The paths, conditions, or boundary governed by this record for README.md.
structurerequired — The structure recorded for this artifact for README.md.
status/review notesoptional — The status/review notes recorded for this artifact for README.md.
Template README.md
# Project name
## Setup
```bash
npm install
npm run dev
```
## Scope
<what this project contains>
## Verification
- `npm run check`
When to use
Use README.md when you need a durable record of orientation, setup, and current project status, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use README.md to replace execution evidence, approval, or a record whose responsibility is outside orientation, setup, and current project status.
intent and allowed pathsrequired — The intent and allowed paths recorded for this artifact for CONTROLLED_VIBE_CODING.md.
diff boundaryrequired — The diff boundary recorded for this artifact for CONTROLLED_VIBE_CODING.md.
check and checkpointrequired — The check and checkpoint recorded for this artifact for CONTROLLED_VIBE_CODING.md.
stop conditionsrequired — The stop conditions recorded for this artifact for CONTROLLED_VIBE_CODING.md.
Template CONTROLLED_VIBE_CODING.md
# CONTROLLED_VIBE_CODING.md
Goal: <one bounded change>
Allowed paths: <explicit files or directories>
Expected diff: <one behavior; no unrelated cleanup>
Check: <targeted command or review step>
Stop when: <scope drift, unclear contract or missing oracle>
Human gate: <continue / revise / HOLD>
Status: documented example; execution result: Unknown.
When to use
Use CONTROLLED_VIBE_CODING.md when you need a durable record of intent, allowed paths, checkpoints, and stop rules, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CONTROLLED_VIBE_CODING.md to replace execution evidence, approval, or a record whose responsibility is outside intent, allowed paths, checkpoints, and stop rules.
Use IMPLEMENTATION_SPRINT_PLAN.md when you need a durable record of one sprint outcome split into owned slices, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use IMPLEMENTATION_SPRINT_PLAN.md to replace execution evidence, approval, or a record whose responsibility is outside one sprint outcome split into owned slices.
demo claimrequired — The demo claim recorded for this artifact for DEMO_QUALITY_GATE.md.
blocking/advisory moderequired — The blocking/advisory mode recorded for this artifact for DEMO_QUALITY_GATE.md.
evidence and thresholdrequired — The evidence and threshold recorded for this artifact for DEMO_QUALITY_GATE.md.
decision and limitsrequired — The decision and limits recorded for this artifact for DEMO_QUALITY_GATE.md.
Template DEMO_QUALITY_GATE.md
# DEMO_QUALITY_GATE.md
Core flow: <bounded scenario>
Blocking: <startup, output and acceptance checks>
Advisory: <non-critical signals>
Evidence: <commands or anchors>
Decision: <GO / HOLD / REDO>
Claims excluded: <production, adoption or scale claims>
Status: documented example; gate result: Unknown.
When to use
Use DEMO_QUALITY_GATE.md when you need a durable record of evidence threshold for a demonstration claim, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use DEMO_QUALITY_GATE.md to replace execution evidence, approval, or a record whose responsibility is outside evidence threshold for a demonstration claim.
environment/startuprequired — The environment/startup recorded for this artifact for DEMO_READINESS.md.
fixtures and expected signalrequired — The fixtures and expected signal recorded for this artifact for DEMO_READINESS.md.
fallback and limitationsrequired — The fallback and limitations recorded for this artifact for DEMO_READINESS.md.
deployment boundaryrequired — The deployment boundary recorded for this artifact for DEMO_READINESS.md.
Template DEMO_READINESS.md
# DEMO_READINESS.md
Scenario: <bounded flow>
Start: <command or manual entry point>
Inputs: <safe fixtures>
Expected signal: <observable output>
Fallback: <static or manual alternative>
Blocking unknowns: <environment or permission gaps>
Deployment boundary: no publish/deploy claim
Status: documented example; readiness result: Unknown.
When to use
Use DEMO_READINESS.md when you need a durable record of repeatable startup, fixtures, and known limitations, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use DEMO_READINESS.md to replace execution evidence, approval, or a record whose responsibility is outside repeatable startup, fixtures, and known limitations.
problem/user/scoperequired — The problem/user/scope recorded for this artifact for CAPSTONE_DEFENSE_HANDOFF.md.
demo and evidence maprequired — The demo and evidence map recorded for this artifact for CAPSTONE_DEFENSE_HANDOFF.md.
limitations and Unknownsrequired — The limitations and Unknowns recorded for this artifact for CAPSTONE_DEFENSE_HANDOFF.md.
decision and ownershiprequired — The decision and ownership recorded for this artifact for CAPSTONE_DEFENSE_HANDOFF.md.
Template CAPSTONE_DEFENSE_HANDOFF.md
# CAPSTONE_DEFENSE_HANDOFF.md
Problem: <bounded problem>
Demo path: <observable steps>
Evidence: <links or anchors>
Known limits: <unsupported cases and Unknowns>
Claims excluded: <production, adoption, scale>
Decision requested: <GO / HOLD / feedback>
Next owner: <role>; next step: <bounded action>
Status: documented example; defense outcome: Unknown.
When to use
Use CAPSTONE_DEFENSE_HANDOFF.md when you need a durable record of the capstone story, evidence map, and decision request, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use CAPSTONE_DEFENSE_HANDOFF.md to replace execution evidence, approval, or a record whose responsibility is outside the capstone story, evidence map, and decision request.
Defines how a bounded scenario and its expected observable signals are captured for a bounded, reviewable engineering workflow.
Documented example
A reader-facing DEMO.md record that keeps a bounded scenario and its expected observable signals explicit for review.
Where it lives
{project}/DEMO.md(repository; documented example)
Fields
audience/scenariorequired — The audience/scenario recorded for this artifact for DEMO.md.
entry point and stepsrequired — The entry point and steps recorded for this artifact for DEMO.md.
expected signalsrequired — The expected signals recorded for this artifact for DEMO.md.
limits and statusrequired — The limits and status recorded for this artifact for DEMO.md.
Template DEMO.md
# DEMO.md
## Scenario
- Audience: <reviewer or evaluation context>
- Core flow: <bounded scenario>
- Entry point: <safe command or manual start>
## Run-through
1. <step and expected signal>
2. <step and expected signal>
3. <step and expected signal>
## Boundaries
- Known limits: <unsupported cases and Unknowns>
- Claims excluded: <production, adoption, scale>
- Status: documented example; demo outcome: Unknown.
When to use
Use DEMO.md when you need a durable record of a bounded scenario and its expected observable signals, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use DEMO.md to replace execution evidence, approval, or a record whose responsibility is outside a bounded scenario and its expected observable signals.
Sourceslevel-31
EVIDENCE_LOG.md
Defines how claims, sources, observations, and ownership over time are captured for a bounded, reviewable engineering workflow.
Documented example
A reader-facing EVIDENCE_LOG.md record that keeps claims, sources, observations, and ownership over time explicit for review.
checkpoint/contextrequired — The checkpoint/context recorded for this artifact for EVIDENCE_LOG.md.
claim/source/resultrequired — The claim/source/result recorded for this artifact for EVIDENCE_LOG.md.
decision/ownerrequired — The decision/owner recorded for this artifact for EVIDENCE_LOG.md.
boundaryrequired — The boundary recorded for this artifact for EVIDENCE_LOG.md.
Template EVIDENCE_LOG.md
# EVIDENCE_LOG.md
## Entry
- Time/context: <bounded checkpoint>
- Claim: <what is being checked>
- Source: <file, command or observation>
- Result: <observed result or Unknown>
- Decision: <continue / revise / HOLD>
- Owner: <role>
## Boundary
- This log does not prove deployment, user validation or production readiness.
- Status: documented example.
When to use
Use EVIDENCE_LOG.md when you need a durable record of claims, sources, observations, and ownership over time, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use EVIDENCE_LOG.md to replace execution evidence, approval, or a record whose responsibility is outside claims, sources, observations, and ownership over time.
Aliases and variants
EVIDENCE.md companion
Sourceslevel-31
HANDOFF_PACKAGE.md
Defines how a linked set of records ready for another reviewer are captured for a bounded, reviewable engineering workflow.
Documented example
A reader-facing HANDOFF_PACKAGE.md record that keeps a linked set of records ready for another reviewer explicit for review.
Use HANDOFF_PACKAGE.md when you need a durable record of a linked set of records ready for another reviewer, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use HANDOFF_PACKAGE.md to replace execution evidence, approval, or a record whose responsibility is outside a linked set of records ready for another reviewer.
Sourceslevel-31
SUBMISSION_PACKAGE.md
Defines how the problem, core flow, start instructions, and status are captured for a bounded, reviewable engineering workflow.
Documented example
A reader-facing SUBMISSION_PACKAGE.md record that keeps the problem, core flow, start instructions, and status explicit for review.
problem and core flowrequired — The problem and core flow recorded for this artifact for SUBMISSION_PACKAGE.md.
start and inputsrequired — The start and inputs recorded for this artifact for SUBMISSION_PACKAGE.md.
expected signal and evidencerequired — The expected signal and evidence recorded for this artifact for SUBMISSION_PACKAGE.md.
limits/statusrequired — The limits/status recorded for this artifact for SUBMISSION_PACKAGE.md.
Template SUBMISSION_PACKAGE.md
# SUBMISSION_PACKAGE.md
Problem: <bounded problem>
Core flow: <one observable scenario>
Start: <safe command or manual entry point>
Inputs: <fixtures without secrets>
Expected signal: <observable output>
Evidence: <diff, checks and notes>
Repro audit: <REPRO_AUDIT.md anchor>
Known limits: <unsupported cases and Unknowns>
Status: documented example; submission and reproducibility result: Unknown.
When to use
Use SUBMISSION_PACKAGE.md when you need a durable record of the problem, core flow, start instructions, and status, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use SUBMISSION_PACKAGE.md to replace execution evidence, approval, or a record whose responsibility is outside the problem, core flow, start instructions, and status.
starting state/prerequisitesrequired — The starting state/prerequisites recorded for this artifact for REPRO_AUDIT.md.
steps and signalsrequired — The steps and signals recorded for this artifact for REPRO_AUDIT.md.
environment gapsrequired — The environment gaps recorded for this artifact for REPRO_AUDIT.md.
decision/statusrequired — The decision/status recorded for this artifact for REPRO_AUDIT.md.
Template REPRO_AUDIT.md
# REPRO_AUDIT.md
Starting state: <clean checkout or documented baseline>
Prerequisites: <versions, commands and safe fixtures>
Steps: <ordered reproduction actions>
Expected: <observable signal>
Observed: <result or Unknown>
Environment gaps: <missing permissions, data or dependencies>
Decision: <reproducible / needs verification / HOLD>
Status: documented example; audit execution: Unknown.
When to use
Use REPRO_AUDIT.md when you need a durable record of whether a result can be reproduced from a stated baseline, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use REPRO_AUDIT.md to replace execution evidence, approval, or a record whose responsibility is outside whether a result can be reproduced from a stated baseline.
audience/problem/claimrequired — The audience/problem/claim recorded for this artifact for DEFENSE_NARRATIVE.md.
path and expected signalsrequired — The path and expected signals recorded for this artifact for DEFENSE_NARRATIVE.md.
evidence/limitsrequired — The evidence/limits recorded for this artifact for DEFENSE_NARRATIVE.md.
decision requestrequired — The decision request recorded for this artifact for DEFENSE_NARRATIVE.md.
Template DEFENSE_NARRATIVE.md
# DEFENSE_NARRATIVE.md
Audience: <reviewer or evaluator>
Problem: <bounded problem and user>
Claim: <what this capstone slice demonstrates>
Path: <three to five actions and expected signals>
Evidence anchors: <files, commands or notes>
Known limits: <Unknowns and unsupported cases>
Decision requested: <GO / HOLD / feedback>
Status: documented example; defense outcome: Unknown.
When to use
Use DEFENSE_NARRATIVE.md when you need a durable record of an audience-facing claim supported by a bounded path, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use DEFENSE_NARRATIVE.md to replace execution evidence, approval, or a record whose responsibility is outside an audience-facing claim supported by a bounded path.
finding and evidencerequired — The finding and evidence recorded for this artifact for REMEDIATION_BACKLOG.md.
priority and ownerrequired — The priority and owner recorded for this artifact for REMEDIATION_BACKLOG.md.
next action/acceptancerequired — The next action/acceptance recorded for this artifact for REMEDIATION_BACKLOG.md.
statusrequired — The status recorded for this artifact for REMEDIATION_BACKLOG.md.
Template REMEDIATION_BACKLOG.md
# REMEDIATION_BACKLOG.md
Source review: <mentor/reviewer note or Unknown>
| Priority | Finding | Evidence | Owner | Acceptance signal | Status |
| --- | --- | --- | --- | --- | --- |
| Must fix | <blocking gap> | <anchor or Unknown> | <role or Unknown> | <observable check> | Needs verification |
| Should fix | <quality improvement> | <anchor or Unknown> | <role or Unknown> | <observable check> | Planned documented example |
| Later | <deferred improvement> | <reason> | <role or Unknown> | <future signal> | Deferred |
Boundary: this backlog does not prove mentor approval or completed remediation.
When to use
Use REMEDIATION_BACKLOG.md when you need a durable record of gaps converted into owned, verifiable follow-up work, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use REMEDIATION_BACKLOG.md to replace execution evidence, approval, or a record whose responsibility is outside gaps converted into owned, verifiable follow-up work.
context and contributionrequired — The context and contribution recorded for this artifact for PORTFOLIO_PACKAGE.md.
flow and evidencerequired — The flow and evidence recorded for this artifact for PORTFOLIO_PACKAGE.md.
evaluation/outcomerequired — The evaluation/outcome recorded for this artifact for PORTFOLIO_PACKAGE.md.
limits/next steprequired — The limits/next step recorded for this artifact for PORTFOLIO_PACKAGE.md.
Template PORTFOLIO_PACKAGE.md
# PORTFOLIO_PACKAGE.md
Title: <capstone name>
Problem and audience: <bounded context>
Role/contribution: <verified contribution or Unknown>
Core flow: <short observable scenario>
Selected evidence: <submission, demo, checks and review anchors>
Evaluation: <rubric summary or Unknown>
Review outcome: <observed decision or Unknown>
Limitations: <unsupported claims and open questions>
Next step: <remediation item or bounded follow-up>
Status: documented example; portfolio publication and external validation: Unknown.
When to use
Use PORTFOLIO_PACKAGE.md when you need a durable record of a concise contribution story backed by selected evidence, with evidence and ownership visible to the next reviewer.
When it is a poor choice
Do not use PORTFOLIO_PACKAGE.md to replace execution evidence, approval, or a record whose responsibility is outside a concise contribution story backed by selected evidence.
problem and audiencerequired — The bounded problem, workflow, and intended reader.
ownership and contributionrequired — The decisions and work owned by the person.
AI assistancerequired — Where AI tools helped without replacing accountability.
evidence and boundaryrequired — The evidence source and claims this record cannot support.
Template AI_NATIVE_POSITIONING.md
# AI_NATIVE_POSITIONING.md\n\nProblem: <bounded problem or workflow>\nOwnership: <decisions and responsibilities>\nAI assistance: <where tools helped>\nEvidence: <verified source or Unknown>\nBoundary: <claims not supported by this record>\nStatus: documented example; hiring outcome: Unknown.\n
When to use
Use AI_NATIVE_POSITIONING.md when you need to explain an AI-native role through responsibility and checkable signals.
When it is a poor choice
Do not use it for an invented job outcome, self-declared seniority, or a substitute for portfolio evidence.
source and signalrequired — The evidence source and observable result.
contributionrequired — The person-owned decision or work.
boundaryrequired — Unknowns and claims outside the evidence.
Template PROOF_OF_WORK_BANK.md
# PROOF_OF_WORK_BANK.md\n\n## Entry\n- Claim: <one concrete statement>\n- Source: <file, diff, command, or review note>\n- Signal: <observed result or Unknown>\n- Contribution: <what I owned>\n- Boundary: <what this does not prove>\n\nStatus: documented example; external validation: Unknown.\n
When to use
Use PROOF_OF_WORK_BANK.md to collect varied, checkable signals without turning them into unsupported marketing claims.
When it is a poor choice
Do not use it for context-free screenshots, raw logs, or proof of external review or employment.
problem and decisionsrequired — The bounded problem, ownership, and trade-offs.
AI assistancerequired — A transparent description of tool assistance.
evidence pathrequired — Observable steps and evidence anchors.
unknowns and decisionrequired — Limits, open questions, and the next request.
Template PORTFOLIO_DEFENSE.md
# PORTFOLIO_DEFENSE.md\n\nProblem: <bounded problem and audience>\nMy decisions: <framing, trade-offs, and checks>\nAI assistance: <generated or assisted parts>\nEvidence path: <anchors and expected signals>\nUnknowns: <open questions>\nDecision requested: <feedback / next check>\nStatus: documented example; interview and hiring outcome: Unknown.\n
When to use
Use PORTFOLIO_DEFENSE.md before a portfolio discussion when you need to show understanding and claim boundaries.
When it is a poor choice
Do not use it to simulate an interview, replace a live technical discussion, or prove a hiring decision.
role and sourcerequired — Target role and source or Unknown.
status and datesrequired — Work status and date of the stored signal.
next actionrequired — One bounded action before the next checkpoint.
evidence and privacyrequired — Anchor, Unknown, and a ban on credentials or unnecessary personal data.
Template APPLICATION_TRACKER.md
# APPLICATION_TRACKER.md\n\n| Role | Source | Status | Next action | Date | Evidence |\n| --- | --- | --- | --- | --- | --- |\n| <role> | <URL or Unknown> | Research / Draft / Ready for review / Unknown | <one bounded action> | <date or Unknown> | <anchor or Unknown> |\n\nPrivacy: do not store credentials, secrets or unnecessary personal data.\nBoundary: tracker status does not prove submission, interview, response or employment.\nStatus: documented example.\n
When to use
Use APPLICATION_TRACKER.md to reduce repeated work and see the next manual action for each role hypothesis.
When it is a poor choice
Do not use it for server-side persistence, automated outreach, mass applications, or secrets.