Cross-Cutting Templates¶
Recommended section name¶
Use Cross-Cutting Templates instead of Shared.
"Shared" is accurate, but too generic. Cross-Cutting Templates says exactly what these artifacts are: reusable records that cut across ES-100 through ES-114 and support the repository as the engineering system of record.
Purpose¶
These templates are not owned by one Engineering Stage. They are reusable artifacts for:
- decisions;
- assumptions;
- evidence;
- issues;
- actions;
- changes;
- meetings;
- reviews;
- repository conventions;
- engineering journal entries.
Use them whenever a stage-specific template is too narrow or when evidence must persist across stages.
Recommended workflow¶
Repository Conventions
↓
Decision Record
↓
Evidence Record
↓
Review Checklist
↓
Issue Log
↓
Action Item Register
↓
Assumption Log
↓
Change Log
↓
Meeting Notes
↓
Engineering JournalCopy location¶
Do not edit reusable templates directly. Copy completed project versions into the appropriate project evidence directory:
docs/project-workspace/<stage-or-area>/
Examples:
docs/project-workspace/architecture/
docs/project-workspace/design/
docs/project-workspace/integration/
docs/project-workspace/release/
docs/project-workspace/stewardship/
docs/project-workspace/shared/
Use docs/project-workspace/shared/ when the artifact is genuinely cross-stage and does not belong cleanly to a single stage.
Template set¶
Repository Conventions
Define directory, naming, evidence, Markdown, review, AI-use, and governance conventions.
02Decision Record
Record decision context, alternatives, rationale, consequences, evidence, follow-up, and supersession.
03Evidence Record
Record what evidence shows, source, supported claims, limitations, reviewer, and follow-up.
04Review Checklist
Define review scope, checklist items, findings, evidence, decision, and required follow-up.
05Issue Log
Track issues, severity, category, owner, evidence, follow-up, status, and carry-forward items.
06Action Item Register
Track actions, source, owner, priority, trigger, status, evidence, and overdue items.
07Assumption Log
Record assumptions, source, impact if wrong, validation plan, owner, status, and retirement.
08Change Log
Record changes, reason, owner, evidence, impact, compatibility, risks, and deferred changes.
09Meeting Notes
Record meeting purpose, participants, topics, decisions, actions, risks, issues, and evidence.
10Engineering Journal
Record engineering observations, progress, significance, evidence created, risks, questions, and next actions.
When to use these templates¶
| Need | Recommended Template |
|---|---|
| A durable decision not covered by a stage-specific ADR/TDR/decision record | decision_record.md |
| Evidence needs to support a claim, review, risk, or release decision | evidence_record.md |
| Review is needed but no stage-specific review template fits | review_checklist.md |
| A problem must be tracked | issue_log.md |
| Work must be assigned and followed through | action_item_register.md |
| A planning assumption needs validation | assumption_log.md |
| A meaningful project/repository change occurred | change_log.md |
| A meeting produced decisions, actions, risks, or evidence | meeting_notes.md |
| Engineering progress or observation should be preserved | engineering_journal.md |
| The project needs consistent repository rules | repository_conventions.md |
Do not use cross-cutting templates as a dumping ground. If a stage-specific artifact exists, use that first. Use these templates when evidence genuinely spans stages or when no stage-specific template fits.
Cross-cutting evidence is what prevents engineering knowledge from evaporating between stages. Decisions, assumptions, issues, actions, and evidence should remain visible long after the original conversation ends.