Artifact-first navigation

Artifact catalog

92 descriptions · 10 categories

A curated registry of artifacts referenced by the guide. “Documented example” describes a form, not a verified physical file.

Example repository organization
some-project/
├── CLAUDE.md                         # project instructions
├── README.md                         # project entry point
├── TASK_SPEC.md                      # task contract
├── SPEC.md                           # project specification
├── CAPSTONE_BRIEF.md                 # capstone brief
├── EVIDENCE.md                       # verification record
├── EVIDENCE_LOG.md                   # legacy evidence alias
├── HANDOFF_NOTE.md                   # handoff context
├── CHANGELOG.md                      # release notes
├── .claude/
│   ├── CLAUDE.local.md               # local context
│   ├── settings.json                 # shared project settings
│   ├── settings.local.json           # local settings
│   ├── rules/                        # scoped rules
│   ├── skills/                       # repeatable workflows
│   ├── agents/                       # custom subagents
│   ├── hooks/                        # hook configuration
│   └── mcp/                          # MCP configuration
├── docs/                             # specification and evidence variants
├── src/
├── scripts/                          # internal checks
├── plugins/                          # plugin distribution
└── working diff                     # current Git diff

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.

CLAUDE.local.md

Defines how machine-specific context that should stay private are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CLAUDE.local.md record that keeps machine-specific context that should stay private explicit for review.

Where it lives
  • .claude/CLAUDE.local.md (repository; documented example)
Fields
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.

.claude/rules/

Defines how scoped rules close to the files they govern are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing .claude/rules/ record that keeps scoped rules close to the files they govern explicit for review.

Where it lives
  • {project}/.claude/rules/ (repository; documented example)
Fields
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.

settings.json

Defines how shared Claude Code permissions and defaults are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing settings.json record that keeps shared Claude Code permissions and defaults explicit for review.

Where it lives
  • {project}/.claude/settings.json (repository; documented example)
  • ~/.claude/settings.json (user; documented example)
Fields
permissionsconventional — Explicitly allowed and denied tool patterns for settings.json.
envoptional — Non-secret environment defaults for the selected scope for settings.json.
scoperequired — The paths, conditions, or boundary governed by this record for settings.json.
version/secret policyconventional — Compatibility notes and the rule that credentials stay out of the file for settings.json.
Template settings.json
{
  "permissions": {
    "allow": ["Bash(npm run check)"],
    "deny": ["Read(.env)"]
  },
  "env": {
    "PROJECT_MODE": "<mode>"
  }
}
When to use

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.

settings.local.json

Defines how developer-local overrides outside the team contract are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing settings.local.json record that keeps developer-local overrides outside the team contract explicit for review.

Where it lives
  • .claude/settings.local.json (repository; documented example)
Fields
settingsconventional — The settings recorded for this artifact for settings.local.json.
ignore policyconventional — The rule that keeps local overrides out of commits for settings.local.json.
Template settings.local.json
{
  "permissions": {
    "allow": ["Bash(npm run check)"],
    "deny": ["Read(.env)"]
  }
}
When to use

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.

AI_CODING_POLICY.md

Defines how allowed AI use, review thresholds, and data boundaries are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing AI_CODING_POLICY.md record that keeps allowed AI use, review thresholds, and data boundaries explicit for review.

Where it lives
  • {project}/AI_CODING_POLICY.md (repository; documented example)
Fields
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.

CODEOWNERS

Defines how ownership rules for protected paths and review are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CODEOWNERS record that keeps ownership rules for protected paths and review explicit for review.

Where it lives
  • .github/CODEOWNERS (repository; documented example)
  • CODEOWNERS (repository; name or path variant)
Fields
patternsrequired — The patterns recorded for this artifact for CODEOWNERS.
ownersrequired — The owners recorded for this artifact for CODEOWNERS.
sensitive areasoptional — The sensitive areas recorded for this artifact for CODEOWNERS.
Template CODEOWNERS
# CODEOWNERS

# Default owner
* @<team-or-role>

# Sensitive area
/src/<area>/** @<approved-owner>

# Configuration
/.claude/** @<workflow-owner>
When to use

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.

CategoryTask definition19 artifacts
TASK_SPEC.md

Defines how a verifiable contract for one bounded change are captured for a bounded, reviewable engineering workflow.

Present in repository

A reader-facing TASK_SPEC.md record that keeps a verifiable contract for one bounded change explicit for review.

Where it lives
  • {project}/TASK_SPEC.md (repository; documented example)
  • archive/task-specs/TASK_SPEC.md (repository; present in repository)
Fields
goal/problemrequired — The problem and outcome that justify the work for TASK_SPEC.md.
current/desired behaviorrequired — The observed state and intended state for TASK_SPEC.md.
scope/non-goalsrequired — Included work and deliberate exclusions for TASK_SPEC.md.
constraintsrequired — Technical, time, policy, or data limits for TASK_SPEC.md.
acceptance criteriarequired — Conditions that make the result reviewable for TASK_SPEC.md.
verification planrequired — Commands or observations used to check the result for TASK_SPEC.md.
risks/open questionsoptional — Unknowns, risks, and decisions still requiring attention for TASK_SPEC.md.
Template TASK_SPEC.md
# Task spec — <short task name>

## Goal
- <problem and desired outcome>

## Scope
- <files or behavior included>

## Non-goals
- <explicitly excluded work>

## Acceptance criteria
- <verifiable condition>

## Verification
- <command or manual check>
When to use

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.

SPEC.md

Defines how the durable product and project contract are captured for a bounded, reviewable engineering workflow.

Name or path variant

A reader-facing SPEC.md record that keeps the durable product and project contract explicit for review.

Where it lives
  • SPEC.md (repository; documented example)
  • docs/SPEC.md (repository; name or path variant)
Fields
project/problemrequired — The project context and problem being addressed for SPEC.md.
audiencerequired — The people for whom the result is designed for SPEC.md.
scope/non-goalsrequired — Included work and deliberate exclusions for SPEC.md.
constraintsrequired — Technical, time, policy, or data limits for SPEC.md.
acceptance criteriarequired — Conditions that make the result reviewable for SPEC.md.
verificationrequired — The planned check and its expected signal for SPEC.md.
Template SPEC.md
# Project specification

## Problem
<problem statement>

## Audience
<primary users>

## Scope
- <included capability>

## Non-goals
- <excluded capability>

## Acceptance criteria
- <measurable result>
When to use

Use SPEC.md when you need a durable record of the durable product and project contract, with evidence and ownership visible to the next reviewer.

When it is a poor choice

Do not use SPEC.md to replace execution evidence, approval, or a record whose responsibility is outside the durable product and project contract.

Aliases and variants

docs/SPEC.md

CAPSTONE_BRIEF.md

Defines how shared expectations and guardrails for a capstone are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CAPSTONE_BRIEF.md record that keeps shared expectations and guardrails for a capstone explicit for review.

Where it lives
  • {project}/CAPSTONE_BRIEF.md (repository; documented example)
Fields
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.

Backlog / roadmap

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.

CONTRACT.md

Defines how interfaces, responsibilities, invariants, and failure behavior are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CONTRACT.md record that keeps interfaces, responsibilities, invariants, and failure behavior explicit for review.

Where it lives
  • {project}/CONTRACT.md (repository; documented example)
Fields
partiesrequired — The parties recorded for this artifact for CONTRACT.md.
input/outputrequired — The input/output recorded for this artifact for CONTRACT.md.
invariants/failuresrequired — The invariants/failures recorded for this artifact for CONTRACT.md.
Template CONTRACT.md
# CONTRACT.md

## Parties
- Producer: <role/component>
- Consumer: <role/component>

## Input
- <required input>

## Output
- <expected output>

## Invariants
- <must remain true>

## Failure/stop conditions
- <condition>
When to use

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.

PLAN.md

Defines how ordered steps, risks, and a stop condition are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing PLAN.md record that keeps ordered steps, risks, and a stop condition explicit for review.

Where it lives
  • {project}/PLAN.md (repository; documented example)
Fields
goal/scoperequired — The goal/scope recorded for this artifact for PLAN.md.
stepsrequired — The steps recorded for this artifact for PLAN.md.
risks/stop conditionrequired — The risks/stop condition recorded for this artifact for PLAN.md.
Template PLAN.md
# PLAN.md

## Goal
<desired outcome>

## Scope
- <included paths or behavior>

## Steps
1. <inspect>
2. <change>
3. <verify>

## Risks
- <risk or none>

## Stop condition
- <when to pause and ask>
When to use

Use PLAN.md when you need a durable record of ordered steps, risks, and a stop condition, with evidence and ownership visible to the next reviewer.

When it is a poor choice

Do not use PLAN.md to replace execution evidence, approval, or a record whose responsibility is outside ordered steps, risks, and a stop condition.

REFACTORING_PLAN.md

Defines how a behavior-preserving structural change plan are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing REFACTORING_PLAN.md record that keeps a behavior-preserving structural change plan explicit for review.

Where it lives
  • {project}/REFACTORING_PLAN.md (repository; documented example)
Fields
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.

MODERNIZATION_ROADMAP.md

Defines how sequenced modernization slices and exit gates are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MODERNIZATION_ROADMAP.md record that keeps sequenced modernization slices and exit gates explicit for review.

Where it lives
  • {project}/MODERNIZATION_ROADMAP.md (repository; documented example)
Fields
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.

MIGRATION_PLAN.md

Defines how phased migration work with evidence gates and rollback are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MIGRATION_PLAN.md record that keeps phased migration work with evidence gates and rollback explicit for review.

Where it lives
  • {project}/MIGRATION_PLAN.md (repository; documented example)
Fields
outcome/scope/non-goalsrequired — The outcome/scope/non-goals recorded for this artifact for MIGRATION_PLAN.md.
phases/ownersrequired — The phases/owners recorded for this artifact for MIGRATION_PLAN.md.
evidence gates/exit criteriarequired — The evidence gates/exit criteria recorded for this artifact for MIGRATION_PLAN.md.
rollback/hold decisionrequired — The rollback/hold decision recorded for this artifact for MIGRATION_PLAN.md.
open risksrequired — The open risks recorded for this artifact for MIGRATION_PLAN.md.
Template MIGRATION_PLAN.md
# MIGRATION_PLAN.md

## Outcome and boundaries
- Source: <current state>
- Target: <target state>
- Scope: <bounded slice>
- Non-goals: <excluded changes>

## Phases
| Phase | Scope | Owner | Evidence gate | Exit criteria | Rollback/HOLD |
| --- | --- | --- | --- | --- | --- |
| Discovery | <facts and unknowns> | <role> | <anchor> | <result> | <hold action> |
| Analysis | <compatibility work> | <role> | <anchor> | <result> | <narrow action> |
| Pilot | <small slice> | <role> | <behavior check> | <result> | <rollback> |

## GO / HOLD decision
- Decision: <GO | HOLD | NARROW | ROLLBACK>
- Evidence: <facts>
- Open risks: <items>
When to use

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.

MIGRATION_TYPES.md

Defines how migration classification, ordering, and ownership are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MIGRATION_TYPES.md record that keeps migration classification, ordering, and ownership explicit for review.

Where it lives
  • {project}/MIGRATION_TYPES.md (repository; documented example)
Fields
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.

DATA_CONFIG_MIGRATION.md

Defines how representation changes, sequencing, integrity, and recovery are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing DATA_CONFIG_MIGRATION.md record that keeps representation changes, sequencing, integrity, and recovery explicit for review.

Where it lives
  • {project}/DATA_CONFIG_MIGRATION.md (repository; documented example)
Fields
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.

VALUE_PROPOSITION.md

Defines how user problem, promised outcome, and proof signal are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing VALUE_PROPOSITION.md record that keeps user problem, promised outcome, and proof signal explicit for review.

Where it lives
  • {project}/VALUE_PROPOSITION.md (repository; documented example)
Fields
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_JTBD.md

Defines how user context, desired progress, pains, gains, and constraints are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing USER_JTBD.md record that keeps user context, desired progress, pains, gains, and constraints explicit for review.

Where it lives
  • {project}/USER_JTBD.md (repository; documented example)
Fields
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.

SUCCESS_METRIC.md

Defines how a measurable outcome with baseline, target, and limits are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing SUCCESS_METRIC.md record that keeps a measurable outcome with baseline, target, and limits explicit for review.

Where it lives
  • {project}/SUCCESS_METRIC.md (repository; documented example)
Fields
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.

RELEASE_SLICE.md

Defines how the smallest coherent flow ready for review are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing RELEASE_SLICE.md record that keeps the smallest coherent flow ready for review explicit for review.

Where it lives
  • {project}/RELEASE_SLICE.md (repository; documented example)
Fields
core flowrequired — The core flow recorded for this artifact for RELEASE_SLICE.md.
in-scope/non-goalsrequired — The in-scope/non-goals recorded for this artifact for RELEASE_SLICE.md.
deferred workoptional — The deferred work recorded for this artifact for RELEASE_SLICE.md.
dependencies/risksrequired — The dependencies/risks recorded for this artifact for RELEASE_SLICE.md.
release criteriarequired — The release criteria recorded for this artifact for RELEASE_SLICE.md.
Template RELEASE_SLICE.md
# RELEASE_SLICE.md

## Core flow
- User: <primary user>
- Trigger: <starting situation>
- Flow: <bounded steps>
- Outcome: <observable result>

## Boundaries
- In scope: <included capabilities>
- Non-goals: <explicit exclusions>
- Deferred: <safe follow-up work>

## Gates
- Dependencies: <known dependencies>
- Risks: <risk and stop condition>
- Release criteria: <reviewable conditions>
- Status: documented example; no release or deployment is claimed.
When to use

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.

CAPSTONE_RUBRIC.md

Defines how evaluation dimensions, evidence anchors, and decision boundaries are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CAPSTONE_RUBRIC.md record that keeps evaluation dimensions, evidence anchors, and decision boundaries explicit for review.

Where it lives
  • {project}/CAPSTONE_RUBRIC.md (repository; documented example)
Fields
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.

TARGET_ROLE_STRATEGY.md

Records target role families, constraints, search hypotheses, and bounded next actions.

Documented example

A job-search planning record that separates a role hypothesis from an application or hiring outcome.

Where it lives
  • {project}/TARGET_ROLE_STRATEGY.md (repository; documented example)
Fields
role familiesrequired — Target role classes and characteristic responsibility.
constraintsrequired — Work format, location, level, and time limits.
evidence and hypothesesrequired — Verified signals and search-hypothesis sources.
next action and boundaryrequired — One manual action and unsupported job-search claims.
Template TARGET_ROLE_STRATEGY.md
# TARGET_ROLE_STRATEGY.md\n\nRole families: <target roles and responsibility>\nConstraints: <location, format, level, time>\nEvidence: <verified proof-of-work or Unknown>\nSearch hypotheses: <source and priority signal>\nNext action: <one bounded manual check>\nBoundary: applications, recruiter responses, interviews and hiring outcome are Unknown.\nStatus: documented example.\n
When to use

Use TARGET_ROLE_STRATEGY.md to focus a search on a few role families and make the next check reviewable.

When it is a poor choice

Do not use it for mass application automation, credentials, or claims about a real hiring outcome.

Aliases and variants

target roles · job search strategy

JOB_FIT_GAP_MAP.md

Compares vacancy requirements with verified evidence, gaps, confidence, and clarification questions.

Documented example

A traceable fit and gap analysis without a verdict about an employer decision.

Where it lives
  • {project}/JOB_FIT_GAP_MAP.md (repository; documented example)
Fields
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.

Aliases and variants

fit map · gap analysis

APPLICATION_TAILORING.md

Controls resume or application adaptation using verified experience and transparent boundaries.

Documented example

A traceable tailoring record that separates the source claim, new emphasis, and Unknown.

Where it lives
  • {project}/APPLICATION_TAILORING.md (repository; documented example)
Fields
target role and source claimrequired — Target role and original verified claim.
relevance and wordingrequired — Reason for adaptation and bounded wording.
not claimedrequired — Missing metrics, employers, outcomes, or reviews.
human checkrequired — Review before any external use.
Template APPLICATION_TAILORING.md
# APPLICATION_TAILORING.md\n\nTarget role: <role or Unknown>\nSource claim: <verified experience or Unknown>\nRole relevance: <why it matters>\nTailored wording: <bounded claim>\nNot claimed: <missing metric, employer, outcome or review>\nHuman check: <required before external submission>\nStatus: documented example; application and hiring outcome: Unknown.\n
When to use

Use APPLICATION_TAILORING.md to adapt professional materials without adding invented experience.

When it is a poor choice

Do not use it to generate fabricated experience, impersonation, or automatic submission of unverified materials.

Aliases and variants

truthful tailoring · tailored application

CategoryEvidence and delivery12 artifacts
EVIDENCE.md

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.

HANDOFF_NOTE.md

Defines how context transfer at a milestone boundary are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing HANDOFF_NOTE.md record that keeps context transfer at a milestone boundary explicit for review.

Where it lives
  • {project}/HANDOFF_NOTE.md (repository; documented example)
Fields
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.

PR description

Defines how review context, checks, risks, and requested attention are captured for a bounded, reviewable engineering workflow.

Operational or external artifact

A reader-facing PR description record that keeps review context, checks, risks, and requested attention explicit for review.

Where it lives
  • pull request description (external; operational or external artifact)
Fields
summaryrequired — The summary recorded for this artifact for PR description.
scoperequired — The paths, conditions, or boundary governed by this record for PR description.
tests/checksrequired — The tests/checks recorded for this artifact for PR description.
risks/review notesoptional — The risks/review notes recorded for this artifact for PR description.
Template PR description
## Summary
<what changed>

## Scope
- Included: <area>
- Not included: <non-goal>

## Checks
- `<command>` — <result>

## Risks
- <risk or none>
When to use

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.

Commit message

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.

Changelog

Defines how user-visible change history and transition notes are captured for a bounded, reviewable engineering workflow.

Operational or external artifact

A reader-facing Changelog record that keeps user-visible change history and transition notes explicit for review.

Where it lives
  • CHANGELOG.md or release notes (repository; operational or external artifact)
Fields
release/versionrequired — The release/version recorded for this artifact for Changelog.
user-visible changesrequired — The user-visible changes recorded for this artifact for Changelog.
migration notesoptional — The migration notes recorded for this artifact for Changelog.
Template Changelog
# Changelog

## [Unreleased]
### Added
- <user-visible capability>

### Fixed
- <user-visible bug fix>

### Migration notes
- <required action or none>
When to use

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.

HANDOFF_REVIEW.md

Defines how an independent review of source, findings, and next decision are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing HANDOFF_REVIEW.md record that keeps an independent review of source, findings, and next decision explicit for review.

Where it lives
  • {project}/HANDOFF_REVIEW.md (repository; documented example)
Fields
source/scoperequired — The source/scope recorded for this artifact for HANDOFF_REVIEW.md.
confirmed/findingsrequired — The confirmed/findings recorded for this artifact for HANDOFF_REVIEW.md.
next decisionrequired — The next decision recorded for this artifact for HANDOFF_REVIEW.md.
Template HANDOFF_REVIEW.md
# HANDOFF_REVIEW.md

## Reviewed handoff
- Source: <handoff path>
- Scope: <reviewed scope>

## Confirmed
- <evidence-backed item>

## Findings
- <finding or none>

## Next decision
- <action and owner>
When to use

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.

Postmortem

Defines how impact, causes, controls, and corrective actions are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing Postmortem record that keeps impact, causes, controls, and corrective actions explicit for review.

Where it lives
  • docs/postmortems/<incident>.md (repository; documented example)
Fields
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.

REVIEW_NOTES.md

Defines how findings, checks, questions, and a cautious verdict are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing REVIEW_NOTES.md record that keeps findings, checks, questions, and a cautious verdict explicit for review.

Where it lives
  • {project}/REVIEW_NOTES.md (repository; documented example)
Fields
scope/findingsrequired — The scope/findings recorded for this artifact for REVIEW_NOTES.md.
checksrequired — The checks recorded for this artifact for REVIEW_NOTES.md.
questions/verdictrequired — The questions/verdict recorded for this artifact for REVIEW_NOTES.md.
Template REVIEW_NOTES.md
# REVIEW_NOTES.md

## Scope reviewed
- <paths or behavior>

## Findings
- <severity> — <file:line> — <finding>

## Checks
- `<command>` — <result>

## Open questions
- <question or none>

## Verdict
<APPROVE | REWORK | HOLD>
When to use

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.

RUNBOOK.md

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.

MODERNIZATION_ANTI_PATTERNS.md

Defines how unsafe modernization habits and safer alternatives are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MODERNIZATION_ANTI_PATTERNS.md record that keeps unsafe modernization habits and safer alternatives explicit for review.

Where it lives
  • {project}/MODERNIZATION_ANTI_PATTERNS.md (repository; documented example)
Fields
anti-pattern/signalrequired — The anti-pattern/signal recorded for this artifact for MODERNIZATION_ANTI_PATTERNS.md.
impactrequired — The impact recorded for this artifact for MODERNIZATION_ANTI_PATTERNS.md.
safer alternativerequired — The safer alternative recorded for this artifact for MODERNIZATION_ANTI_PATTERNS.md.
stop condition/evidencerequired — The stop condition/evidence recorded for this artifact for MODERNIZATION_ANTI_PATTERNS.md.
Template MODERNIZATION_ANTI_PATTERNS.md
# MODERNIZATION_ANTI_PATTERNS.md

## Anti-pattern: <name>
- Signal: <observable warning>
- Impact: <possible consequence>
- Safer alternative: <bounded practice>
- Stop condition: <when to pause>
- Evidence: <anchor>
When to use

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.

MIGRATION_VALIDATION_REPORT.md

Defines how expected versus observed migration behavior are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MIGRATION_VALIDATION_REPORT.md record that keeps expected versus observed migration behavior explicit for review.

Where it lives
  • {project}/MIGRATION_VALIDATION_REPORT.md (repository; documented example)
Fields
baseline/scoperequired — The baseline/scope recorded for this artifact for MIGRATION_VALIDATION_REPORT.md.
validation dimensionsrequired — The validation dimensions recorded for this artifact for MIGRATION_VALIDATION_REPORT.md.
expected/observed/evidencerequired — The expected/observed/evidence recorded for this artifact for MIGRATION_VALIDATION_REPORT.md.
discrepancy/decisionrequired — The discrepancy/decision recorded for this artifact for MIGRATION_VALIDATION_REPORT.md.
limits/ownerrequired — The limits/owner recorded for this artifact for MIGRATION_VALIDATION_REPORT.md.
Template MIGRATION_VALIDATION_REPORT.md
# MIGRATION_VALIDATION_REPORT.md

## Scope and baseline
- Source revision: <revision>
- Target revision: <revision>
- Pilot slice: <bounded surface>

## Checks
| Dimension | Expected | Observed | Evidence anchor | Status |
| --- | --- | --- | --- | --- |
| behavior inputs/outputs/errors/side effects | <contract> | <observation> | <test/log/fixture> | <pass/fail/Unknown> |
| data integrity and counts | <invariant> | <observation> | <command/result> | <pass/fail/Unknown> |
| configuration and startup | <expected mapping> | <observation> | <check> | <pass/fail/Unknown> |

## Decision
- Discrepancies: <none or described>
- Decision: <GO | HOLD | NARROW | ROLLBACK>
- Confidence and limits: <what remains Unknown>
- Status: documented example; no migration validation was executed.
When to use

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.

POST_MIGRATION_NOTES.md

Defines how the decision record after a migration checkpoint are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing POST_MIGRATION_NOTES.md record that keeps the decision record after a migration checkpoint explicit for review.

Where it lives
  • {project}/POST_MIGRATION_NOTES.md (repository; documented example)
Fields
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.

CategoryCodebase understanding16 artifacts
CODEBASE_INVENTORY.md

Defines how a compact map of repository structure and risk are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CODEBASE_INVENTORY.md record that keeps a compact map of repository structure and risk explicit for review.

Where it lives
  • {project}/CODEBASE_INVENTORY.md (repository; documented example)
Fields
stackrequired — Languages, frameworks, and tools in use for CODEBASE_INVENTORY.md.
system partsrequired — Major modules and their boundaries for CODEBASE_INVENTORY.md.
entry pointsrequired — Where execution begins for CODEBASE_INVENTORY.md.
run/check commandsrequired — How to start and verify the system for CODEBASE_INVENTORY.md.
runtime flowsoptional — Important data or control-flow paths for CODEBASE_INVENTORY.md.
risk areas/open questionsoptional — Risk areas and unresolved questions for CODEBASE_INVENTORY.md.
Template CODEBASE_INVENTORY.md
# Codebase inventory

## Stack
- Language: <language>
- Framework: <framework>

## Entry points
- <path> — <purpose>

## Commands
- Run: `<command>`
- Check: `<command>`

## Risk areas
- <area and reason>
When to use

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.

API_MAP.md

Defines how traceability across routes, handlers, and integration boundaries are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing API_MAP.md record that keeps traceability across routes, handlers, and integration boundaries explicit for review.

Where it lives
  • {project}/API_MAP.md (repository; documented example)
Fields
route/handlerrequired — The entry point and handler responsible for it for API_MAP.md.
integration/data boundaryrequired — The database, queue, or external client boundary for API_MAP.md.
tests/envoptional — Checks and configuration dependencies for API_MAP.md.
Template API_MAP.md
# API map

| Route | Handler | Boundary | Checks |
| --- | --- | --- | --- |
| `GET /<resource>` | `<handler>` | `<DB or service>` | `<test>` |

## Environment
- `<ENV_NAME>` — <purpose>
When to use

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.

CLAWD Wisdom

Defines how contextual advice tied to evidence and limitations are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CLAWD Wisdom record that keeps contextual advice tied to evidence and limitations explicit for review.

Where it lives
  • .claude/knowledge/CLAWD-Wisdom.md (repository; documented example)
Fields
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.

research-digest.md

Defines how a research question, source trail, and bounded recommendation are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing research-digest.md record that keeps a research question, source trail, and bounded recommendation explicit for review.

Where it lives
  • sources/research-digest.md (repository; documented example)
Fields
questionrequired — The question recorded for this artifact for research-digest.md.
sources/findingsrequired — The sources/findings recorded for this artifact for research-digest.md.
unknowns/recommendationrequired — The unknowns/recommendation recorded for this artifact for research-digest.md.
Template research-digest.md
# Research digest

## Question
<question>

## Sources
- <source> — <what it supports>

## Findings
- <confirmed finding>

## Unknowns
- <unverified item>

## Recommendation
<next safe step>
When to use

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.

DEBT_SIGNALS.md

Defines how observable indicators of legacy risk are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing DEBT_SIGNALS.md record that keeps observable indicators of legacy risk explicit for review.

Where it lives
  • {project}/DEBT_SIGNALS.md (repository; documented example)
Fields
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.

RISK_MAP.md

Defines how criticality, change risk, evidence gaps, and action are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing RISK_MAP.md record that keeps criticality, change risk, evidence gaps, and action explicit for review.

Where it lives
  • {project}/RISK_MAP.md (repository; documented example)
Fields
area/criticalityrequired — The area/criticality recorded for this artifact for RISK_MAP.md.
change risk/categoriesrequired — The change risk/categories recorded for this artifact for RISK_MAP.md.
evidence/missing checksrequired — The evidence/missing checks recorded for this artifact for RISK_MAP.md.
recommended actionrequired — The recommended action recorded for this artifact for RISK_MAP.md.
Template RISK_MAP.md
# RISK_MAP.md

## Risk entries
| Area | Business criticality | Change risk | Categories | Evidence | Missing checks | Recommended action |
| --- | --- | --- | --- | --- | --- | --- |
| <area> | <low|medium|high> | <low|medium|high> | <categories> | <anchors> | <checks> | <decision> |

## Unknowns
- <unknown and owner or verification step>
When to use

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.

ARCHITECTURE_CURRENT.md

Defines how confirmed architecture facts and unresolved discrepancies are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing ARCHITECTURE_CURRENT.md record that keeps confirmed architecture facts and unresolved discrepancies explicit for review.

Where it lives
  • {project}/ARCHITECTURE_CURRENT.md (repository; documented example)
Fields
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.

BEHAVIOR_INVENTORY.md

Defines how current observable behavior and characterization candidates are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing BEHAVIOR_INVENTORY.md record that keeps current observable behavior and characterization candidates explicit for review.

Where it lives
  • {project}/BEHAVIOR_INVENTORY.md (repository; documented example)
Fields
flow/current behaviorrequired — The flow/current behavior recorded for this artifact for BEHAVIOR_INVENTORY.md.
inputs/outputsrequired — The inputs/outputs recorded for this artifact for BEHAVIOR_INVENTORY.md.
tests/missing checksrequired — The tests/missing checks recorded for this artifact for BEHAVIOR_INVENTORY.md.
characterization candidaterequired — The characterization candidate recorded for this artifact for BEHAVIOR_INVENTORY.md.
evidencerequired — The evidence recorded for this artifact for BEHAVIOR_INVENTORY.md.
Template BEHAVIOR_INVENTORY.md
# BEHAVIOR_INVENTORY.md

## Flow: <business flow>
- Current behavior: <confirmed facts and confidence>
- Inputs: <reproducible inputs>
- Outputs: <observable outputs>
- Existing tests: <paths and level>
- Missing checks: <gaps>
- Characterization candidate: <yes|no> — <reason>
- Evidence: <anchors>
When to use

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.

CRITICAL_FLOWS.md

Defines how business-critical runtime paths and failure handling are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CRITICAL_FLOWS.md record that keeps business-critical runtime paths and failure handling explicit for review.

Where it lives
  • {project}/CRITICAL_FLOWS.md (repository; documented example)
Fields
trigger/inputsrequired — The trigger/inputs recorded for this artifact for CRITICAL_FLOWS.md.
steps/boundariesrequired — The steps/boundaries recorded for this artifact for CRITICAL_FLOWS.md.
side effects/outputrequired — The side effects/output recorded for this artifact for CRITICAL_FLOWS.md.
failure path/evidencerequired — The failure path/evidence recorded for this artifact for CRITICAL_FLOWS.md.
Template CRITICAL_FLOWS.md
# CRITICAL_FLOWS.md

## Flow: <name>
- Trigger: <event or entry point>
- Inputs: <state and data>
- Steps: <ordered components>
- Side effects: <writes, integrations, notifications>
- Output: <observable result>
- Failure path: <error, retry, rollback, or escalation>
- Evidence: <anchors>
When to use

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_INVENTORY.md

Defines how module boundaries, entry points, dependencies, and risks are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MODULE_INVENTORY.md record that keeps module boundaries, entry points, dependencies, and risks explicit for review.

Where it lives
  • {project}/MODULE_INVENTORY.md (repository; documented example)
Fields
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.

MODERNIZATION_BASELINE.md

Defines how a behavior baseline for a safe modernization slice are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MODERNIZATION_BASELINE.md record that keeps a behavior baseline for a safe modernization slice explicit for review.

Where it lives
  • {project}/MODERNIZATION_BASELINE.md (repository; documented example)
Fields
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.

SEAM_MAP.md

Defines how candidate boundaries where dependencies can be controlled are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing SEAM_MAP.md record that keeps candidate boundaries where dependencies can be controlled explicit for review.

Where it lives
  • {project}/SEAM_MAP.md (repository; documented example)
Fields
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.

MIGRATION_DISCOVERY.md

Defines how source state, target intent, and migration unknowns are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MIGRATION_DISCOVERY.md record that keeps source state, target intent, and migration unknowns explicit for review.

Where it lives
  • {project}/MIGRATION_DISCOVERY.md (repository; documented example)
Fields
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.

CHANGELOG_RESEARCH.md

Defines how official release changes and their possible impact are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CHANGELOG_RESEARCH.md record that keeps official release changes and their possible impact explicit for review.

Where it lives
  • {project}/CHANGELOG_RESEARCH.md (repository; documented example)
Fields
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.

DEPENDENCY_GRAPH.md

Defines how directed dependency relationships and affected flows are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing DEPENDENCY_GRAPH.md record that keeps directed dependency relationships and affected flows explicit for review.

Where it lives
  • {project}/DEPENDENCY_GRAPH.md (repository; documented example)
Fields
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.

COMPATIBILITY_MATRIX.md

Defines how source-to-target compatibility decisions by dimension are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing COMPATIBILITY_MATRIX.md record that keeps source-to-target compatibility decisions by dimension explicit for review.

Where it lives
  • {project}/COMPATIBILITY_MATRIX.md (repository; documented example)
Fields
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.

CategoryReusable workflows7 artifacts
SKILL.md

Defines how a repeatable procedure with a stable trigger are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing SKILL.md record that keeps a repeatable procedure with a stable trigger explicit for review.

Where it lives
  • {project}/.claude/skills/{skill-name}/SKILL.md (repository; documented example)
  • ~/.claude/skills/{skill-name}/SKILL.md (user; documented example)
Fields
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.

Custom subagent

Defines how a constrained role for focused discovery or review are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing Custom subagent record that keeps a constrained role for focused discovery or review explicit for review.

Where it lives
  • {project}/.claude/agents/reviewer.md (repository; documented example)
  • ~/.claude/agents/{name}.md (user; documented example)
Fields
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.

Hook configuration

Defines how event-driven local automation with an escape hatch are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing Hook configuration record that keeps event-driven local automation with an escape hatch explicit for review.

Where it lives
  • {project}/.claude/hooks/ (repository; documented example)
Fields
eventrequired — The lifecycle event that starts automation for Hook configuration.
matcherrequired — The condition that narrows the event scope for Hook configuration.
handlerrequired — The one action or command that runs for Hook configuration.
mode/kill switchconventional — Blocking behavior and the way to disable it for Hook configuration.
Template Hook configuration
event: <lifecycle-event>
matcher: <path-or-condition>
handler: <command-or-script>
mode: non-blocking
kill_switch: <how-to-disable>
When to use

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.

Plugin

Defines how a packaged Claude Code extension and its permissions are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing Plugin record that keeps a packaged Claude Code extension and its permissions explicit for review.

Where it lives
  • Plugin package (external; documented example)
Fields
manifestrequired — The manifest recorded for this artifact for Plugin.
workflow assetsrequired — The workflow assets recorded for this artifact for Plugin.
versionrequired — The version recorded for this artifact for Plugin.
permissions/integration notesconventional — The permissions/integration notes recorded for this artifact for Plugin.
Template Plugin
name: <plugin-name>
version: 0.1.0
manifest:
  skills:
    - <skill-name>
  agents:
    - <agent-name>
permissions:
  - <required-access>
When to use

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.

commands.md

Defines how a runnable command catalog with expected signals are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing commands.md record that keeps a runnable command catalog with expected signals explicit for review.

Where it lives
  • {project}/commands.md (repository; documented example)
Fields
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.

CLAWD YOLO

Defines how a deliberately narrow high-autonomy permission boundary are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CLAWD YOLO record that keeps a deliberately narrow high-autonomy permission boundary explicit for review.

Where it lives
  • .claude/workflows/CLAWD-YOLO.md (repository; documented example)
Fields
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.

workflow.md

Defines how stages, owners, inputs, and failure handling are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing workflow.md record that keeps stages, owners, inputs, and failure handling explicit for review.

Where it lives
  • {project}/workflow.md (repository; documented example)
Fields
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.

CategoryIntegrations1 artifacts
MCP

Defines how the connection, scope, and health contract for an MCP server are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing MCP record that keeps the connection, scope, and health contract for an MCP server explicit for review.

Where it lives
  • {project}/.claude/mcp/ (repository; documented example)
Fields
transportrequired — The transport recorded for this artifact for MCP.
scoperequired — The paths, conditions, or boundary governed by this record for MCP.
authrequired — The auth recorded for this artifact for MCP.
status/healthconventional — The status/health recorded for this artifact for MCP.
Template MCP
server: <server-name>
transport: <stdio|http>
command: <command>
scope: project
auth: REDACTED
healthcheck: <status command>
When to use

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.

CategoryExecution and quality9 artifacts
Git branch / worktree / diff

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.

CLAWD Runner

Defines how the input, environment, and outcome of an automated run are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CLAWD Runner record that keeps the input, environment, and outcome of an automated run explicit for review.

Where it lives
  • .claude/runs/<run-id>.md (generated; documented example)
Fields
inputrequired — The input recorded for this artifact for CLAWD Runner.
command/environmentrequired — The command/environment recorded for this artifact for CLAWD Runner.
status/outputrequired — The status/output recorded for this artifact for CLAWD Runner.
Template CLAWD Runner
# CLAWD Runner

run: <human-readable name>
input: <path or task id>
command: `<command>`
environment: <local|ci|staging>
status: <planned|running|passed|failed|stopped>
output: <artifact path or summary>
When to use

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.

locales.json

Defines how supported locales and fallback namespace configuration are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing locales.json record that keeps supported locales and fallback namespace configuration explicit for review.

Where it lives
  • {project}/locales.json (repository; documented example)
Fields
defaultLocalerequired — The defaultLocale recorded for this artifact for locales.json.
supportedLocalesrequired — The supportedLocales recorded for this artifact for locales.json.
fallbackLocale/namespacesrequired — The fallbackLocale/namespaces recorded for this artifact for locales.json.
Template locales.json
{
  "defaultLocale": "<locale>",
  "supportedLocales": ["<locale>"],
  "fallbackLocale": "<locale>",
  "namespaces": ["<namespace>"]
}
When to use

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.

Locale API/UI/test bundle

Defines how locale keys across API, UI, and test layers are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing Locale API/UI/test bundle record that keeps locale keys across API, UI, and test layers explicit for review.

Where it lives
  • locale API/UI/test change set (repository; documented example)
Fields
locale/keysrequired — The locale/keys recorded for this artifact for Locale API/UI/test bundle.
layersrequired — The layers recorded for this artifact for Locale API/UI/test bundle.
verificationrequired — The planned check and its expected signal for Locale API/UI/test bundle.
Template Locale API/UI/test bundle
# Locale bundle

## Contract
- Locale: <locale>
- Keys added/changed: <keys>

## Layers
- API: <paths>
- UI: <paths>
- Tests: <paths>

## Verification
- `<command>` — <result>
When to use

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.

run-status.yaml

Defines how machine-readable lifecycle state and stage evidence are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing run-status.yaml record that keeps machine-readable lifecycle state and stage evidence explicit for review.

Where it lives
  • .claude/runs/run-status.yaml (generated; documented example)
Fields
workflow/statusrequired — The workflow/status recorded for this artifact for run-status.yaml.
stagesrequired — The stages recorded for this artifact for run-status.yaml.
run_id/updated_atconventional — The run id/updated at recorded for this artifact for run-status.yaml.
Template run-status.yaml
run_id: <opaque-id>
workflow: <name>
status: <planned|running|passed|failed|stopped>
stages:
  - name: <stage>
    status: <status>
    evidence: <path-or-summary>
updated_at: <timestamp>
When to use

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.

diagnosis.json

Defines how a compact status classification with confidence and next action are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing diagnosis.json record that keeps a compact status classification with confidence and next action explicit for review.

Where it lives
  • .claude/diagnosis/diagnosis.json (generated; documented example)
Fields
status/classrequired — The status/class recorded for this artifact for diagnosis.json.
evidencerequired — The evidence recorded for this artifact for diagnosis.json.
confidence/nextActionrequired — The confidence/nextAction recorded for this artifact for diagnosis.json.
Template diagnosis.json
{
  "status": "<failure|healthy|unknown>",
  "class": "<test|build|environment|flaky|contract>",
  "evidence": ["<redacted-log-line>"],
  "confidence": "<high|medium|low>",
  "nextAction": "<safe next step>"
}
When to use

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.

CHARACTERIZATION_TESTS.md

Defines how baseline cases and observable behavior before change are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CHARACTERIZATION_TESTS.md record that keeps baseline cases and observable behavior before change explicit for review.

Where it lives
  • {project}/CHARACTERIZATION_TESTS.md (repository; documented example)
Fields
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.

STRANGLER_SLICE.md

Defines how an incremental legacy/new coexistence boundary are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing STRANGLER_SLICE.md record that keeps an incremental legacy/new coexistence boundary explicit for review.

Where it lives
  • {project}/STRANGLER_SLICE.md (repository; documented example)
Fields
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.

ROLLBACK.md

Defines how recoverable triggers, ordered actions, and post-recovery checks are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing ROLLBACK.md record that keeps recoverable triggers, ordered actions, and post-recovery checks explicit for review.

Where it lives
  • {project}/ROLLBACK.md (repository; documented example)
Fields
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.

CategoryThis site artifacts1 artifacts
README.md

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.

CategoryExecution and control2 artifacts
CONTROLLED_VIBE_CODING.md

Defines how intent, allowed paths, checkpoints, and stop rules are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CONTROLLED_VIBE_CODING.md record that keeps intent, allowed paths, checkpoints, and stop rules explicit for review.

Where it lives
  • {project}/CONTROLLED_VIBE_CODING.md (repository; documented example)
Fields
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.

IMPLEMENTATION_SPRINT_PLAN.md

Defines how one sprint outcome split into owned slices are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing IMPLEMENTATION_SPRINT_PLAN.md record that keeps one sprint outcome split into owned slices explicit for review.

Where it lives
  • {project}/IMPLEMENTATION_SPRINT_PLAN.md (repository; documented example)
Fields
objective and boundariesrequired — The objective and boundaries recorded for this artifact for IMPLEMENTATION_SPRINT_PLAN.md.
slices and ownerrequired — The slices and owner recorded for this artifact for IMPLEMENTATION_SPRINT_PLAN.md.
checkpointsrequired — The checkpoints recorded for this artifact for IMPLEMENTATION_SPRINT_PLAN.md.
exit decisionrequired — The exit decision recorded for this artifact for IMPLEMENTATION_SPRINT_PLAN.md.
Template IMPLEMENTATION_SPRINT_PLAN.md
# IMPLEMENTATION_SPRINT_PLAN.md

Outcome: <reviewable increment>
Slices: <ordered implementation slices>
Owner: <role>
Dependencies: <known prerequisites>
Checkpoint: <diff and verification review>
Exit: <DONE / CONTINUE WITH APPROVAL / HOLD>
Deferred: <excluded work>
Status: documented example; sprint execution: Unknown.
When to use

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.

CategoryVerification, handoff, and delivery18 artifacts
DEMO_QUALITY_GATE.md

Defines how evidence threshold for a demonstration claim are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing DEMO_QUALITY_GATE.md record that keeps evidence threshold for a demonstration claim explicit for review.

Where it lives
  • {project}/DEMO_QUALITY_GATE.md (repository; documented example)
Fields
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.

DEMO_READINESS.md

Defines how repeatable startup, fixtures, and known limitations are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing DEMO_READINESS.md record that keeps repeatable startup, fixtures, and known limitations explicit for review.

Where it lives
  • {project}/DEMO_READINESS.md (repository; documented example)
Fields
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.

CAPSTONE_DEFENSE_HANDOFF.md

Defines how the capstone story, evidence map, and decision request are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing CAPSTONE_DEFENSE_HANDOFF.md record that keeps the capstone story, evidence map, and decision request explicit for review.

Where it lives
  • {project}/CAPSTONE_DEFENSE_HANDOFF.md (repository; documented example)
Fields
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.

DEMO.md

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.

Where it lives
  • {project}/EVIDENCE_LOG.md (repository; documented example)
Fields
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.

Where it lives
  • {project}/HANDOFF_PACKAGE.md (repository; documented example)
Fields
summary and scoperequired — The summary and scope recorded for this artifact for HANDOFF_PACKAGE.md.
linked package recordsrequired — The linked package records recorded for this artifact for HANDOFF_PACKAGE.md.
limitations/questionsrequired — The limitations/questions recorded for this artifact for HANDOFF_PACKAGE.md.
decision/ownershiprequired — The decision/ownership recorded for this artifact for HANDOFF_PACKAGE.md.
Template HANDOFF_PACKAGE.md
# HANDOFF_PACKAGE.md

## Summary
- Problem: <bounded problem>
- User: <primary user or reviewer>
- Scope: <implemented/documented slice>

## Package
- Demo: <DEMO.md anchor>
- Quality gate: <DEMO_QUALITY_GATE.md anchor>
- Readiness: <DEMO_READINESS.md anchor>
- Evidence log: <EVIDENCE_LOG.md anchor>
- Defense handoff: <CAPSTONE_DEFENSE_HANDOFF.md anchor>

## Decision
- Requested: <GO / HOLD / feedback>
- Next owner: <role>
- Status: documented example; handoff outcome: Unknown.
When to use

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.

Where it lives
  • {project}/SUBMISSION_PACKAGE.md (repository; documented example)
Fields
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.

REPRO_AUDIT.md

Defines how whether a result can be reproduced from a stated baseline are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing REPRO_AUDIT.md record that keeps whether a result can be reproduced from a stated baseline explicit for review.

Where it lives
  • {project}/REPRO_AUDIT.md (repository; documented example)
Fields
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.

DEFENSE_NARRATIVE.md

Defines how an audience-facing claim supported by a bounded path are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing DEFENSE_NARRATIVE.md record that keeps an audience-facing claim supported by a bounded path explicit for review.

Where it lives
  • {project}/DEFENSE_NARRATIVE.md (repository; documented example)
Fields
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.

REMEDIATION_BACKLOG.md

Defines how gaps converted into owned, verifiable follow-up work are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing REMEDIATION_BACKLOG.md record that keeps gaps converted into owned, verifiable follow-up work explicit for review.

Where it lives
  • {project}/REMEDIATION_BACKLOG.md (repository; documented example)
Fields
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.

PORTFOLIO_PACKAGE.md

Defines how a concise contribution story backed by selected evidence are captured for a bounded, reviewable engineering workflow.

Documented example

A reader-facing PORTFOLIO_PACKAGE.md record that keeps a concise contribution story backed by selected evidence explicit for review.

Where it lives
  • {project}/PORTFOLIO_PACKAGE.md (repository; documented example)
Fields
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.

AI_NATIVE_POSITIONING.md

Captures bounded professional positioning through problem, ownership, evidence, and claim boundaries.

Documented example

A reader-facing positioning record that separates personal responsibility from tool output and unverified career claims.

Where it lives
  • {project}/AI_NATIVE_POSITIONING.md (repository; documented example)
Fields
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.

PROOF_OF_WORK_BANK.md

Collects small proof-of-work records with a claim, source, signal, and explicit conclusion boundary.

Documented example

A reader-facing index of evidence entries that preserves traceability from task to checkable signal.

Where it lives
  • {project}/PROOF_OF_WORK_BANK.md (repository; documented example)
Fields
claimrequired — One narrow, reviewable statement.
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.

CAREER_NARRATIVE.md

Connects responsibility level, career story, trade-offs, and proof-of-work.

Documented example

A reviewer-facing narrative for honest Junior, Middle, or Senior scope claims.

Where it lives
  • {project}/CAREER_NARRATIVE.md (repository; documented example)
Fields
level framerequired — The responsibility boundary being described.
context and ownershiprequired — The problem, audience, and contribution.
trade-offsrequired — The decision rationale and deferred alternatives.
evidence and next steprequired — Proof anchors, Unknowns, and bounded follow-up.
Template CAREER_NARRATIVE.md
# CAREER_NARRATIVE.md\n\nLevel frame: <Junior / Middle / Senior>\nContext: <problem and audience>\nOwnership: <decisions and contribution>\nTrade-offs: <choice and deferred alternative>\nEvidence: <anchors or Unknown>\nNext step: <bounded follow-up>\nStatus: documented example; seniority validation: Unknown.\n
When to use

Use CAREER_NARRATIVE.md to turn evidence entries into a coherent, level-calibrated professional story.

When it is a poor choice

Do not use it to determine seniority automatically, invent employment history, or replace evidence.

AI_NATIVE_RESUME.md

Aligns a resume, repository profile, and professional story around verified contribution.

Documented example

A reader-facing profile package for honest AI-native positioning across resume, GitHub, and LinkedIn.

Where it lives
  • {project}/AI_NATIVE_RESUME.md (repository; documented example)
Fields
headline and outcomerequired — A concise capability and bounded result.
contributionrequired — Work owned by the candidate.
cross-surface linksrequired — Resume, repository, and profile references.
AI disclosure and limitsrequired — Transparent assistance and unsupported claims.
Template AI_NATIVE_RESUME.md
# AI_NATIVE_RESUME.md\n\nHeadline: <bounded capability>\nEvidence-backed outcome: <observable signal or Unknown>\nContribution: <what I owned>\nRepository link: <verified link or Unknown>\nProfile summary: <consistent narrative>\nAI disclosure: <transparent assistance boundary>\nStatus: documented example; review and hiring outcome: Unknown.\n
When to use

Use AI_NATIVE_RESUME.md to align resume, GitHub, and LinkedIn around one evidence-backed narrative.

When it is a poor choice

Do not use it for fabricated metrics, unverified public links, or a claim that a resume was accepted or led to hiring.

PORTFOLIO_DEFENSE.md

Prepares an honest explanation of ownership, AI assistance, verification, and portfolio claim boundaries.

Documented example

A reviewer-facing defense outline for the question “you or AI?” without denying tools or inventing contribution.

Where it lives
  • {project}/PORTFOLIO_DEFENSE.md (repository; documented example)
Fields
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.

APPLICATION_TRACKER.md

Organizes roles, sources, statuses, next actions, dates, and evidence in a privacy-safe career workspace.

Documented example

A minimal tracker for memory and handoff that does not replace evidence of an application outcome.

Where it lives
  • {project}/APPLICATION_TRACKER.md (repository; documented example)
Fields
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.

Aliases and variants

career workspace · application log

ASSESSMENT_FEEDBACK_LOOP.md

Records an assessment or take-home contract, expected signals, observations, feedback status, and remediation action.

Documented example

A feedback loop for learning and next iteration without inventing a hiring verdict.

Where it lives
  • {project}/ASSESSMENT_FEEDBACK_LOOP.md (repository; documented example)
Fields
assessment contractrequired — Prompt, source, timebox, and allowed tools.
expected and observed signalrequired — Criterion and actual result or Unknown.
feedback status and gaprequired — Feedback received/requested/Unknown and verified gap.
next action and boundaryrequired — Remediation step and hiring-claim boundary.
Template ASSESSMENT_FEEDBACK_LOOP.md
# ASSESSMENT_FEEDBACK_LOOP.md\n\nAssessment/source: <prompt, review note or Unknown>\nTimebox and allowed tools: <bounded constraints>\nExpected signal: <observable criterion>\nObserved result: <result or Unknown>\nFeedback status: received / requested / Unknown\nGap: <verified finding or personal hypothesis>\nNext action: <one remediation step>\nBoundary: assessment, interview, pass/fail and hiring outcome are Unknown unless separately evidenced.\nStatus: documented example.\n
When to use

Use ASSESSMENT_FEEDBACK_LOOP.md to plan an assessment or turn verified feedback into a small next action.

When it is a poor choice

Do not use it for an invented interview transcript, automatic pass/fail, or a hiring-decision claim.

Aliases and variants

take-home · feedback loop

Top