| name | engineering-journal |
| description | Use when starting, continuing, handing off, or closing a non-trivial engineering or research effort in a shared repository; when preserving a measured negative result; when reconciling journal status, index, or backlog drift; or when identifying journal material that may inform future problem or design briefs. |
Engineering Journal
Purpose
Keep one durable, repository-local record per non-trivial effort: its goal,
evidence, decisions, implementation, outcome, and unresolved work. Issues and
pull requests remain the task layer; the journal is the narrative and decision
layer. Do not use it for self-evident one-line changes.
Discover the Repository Convention
Before writing, inspect repository instructions and search for docs/journal/,
journal/, an index, backlog, roadmap, assumptions, canonical facts or data,
and existing entry frontmatter. Preserve established paths, headings, extra
metadata, and derived-document conventions.
If no convention exists, use docs/journal/YYYY-MM-DD-short-slug.md and
docs/journal/README.md. Bootstrap both from the templates below. Do not create
a project-wide backlog unless the user requests one.
Search the journal and Git history for prior work before opening a new entry.
Choose the Lifecycle
Support both modes:
- intent-first — land an
open entry before implementation when early
visibility, coordination, or a GO/NO-GO probe matters; close it later.
- single-PR — create and close the entry in the implementation PR when work
is already underway or tightly scoped.
State which mode you are using. Honor an explicit user choice.
Frontmatter State
Frontmatter is authoritative:
---
status: open
opened: YYYY-MM-DD
updated: YYYY-MM-DD
---
Allowed states:
status: open — active, paused, or blocked. Record the blocker and restart
condition in the body; do not invent a paused state.status: shipped — landed with implementation and verification evidence.status: no-go — rejected or falsified with the mechanism and a concrete
reopen condition.status: superseded — replaced by an existing entry; require
superseded_by: <entry-slug>.
Optional fields such as issues: [123], prs: [456], and
beta_skills: [architecture-diagram] appear only when they apply. Never invent
lifecycle dates, links, measurements, or evidence.
Valid transitions are open to any terminal state, and shipped or no-go to
superseded when a replacement entry exists. Do not reopen terminal entries in
place; open a new entry that links the prior result. Use superseded_by only on
superseded entries.
Entry Template
---
status: open
opened: YYYY-MM-DD
updated: YYYY-MM-DD
---
# <Effort title>
## Goal
## Decision Criteria
## Scope
## Evidence
## Design and Implementation
## Outcome
## Derived Documents
## Deferred or Reopen Items
## Skill Feedback
## Appendix: Skills Invoked
Omit Decision Criteria only when there is no meaningful GO/NO-GO gate. While
open, state the current result or say explicitly that the outcome remains open.
The last two headings follow the rules in Record Skill Use below.
Ground claims in durable source paths, commit SHAs, pull requests, measurements,
or canonical datasets. Mark unverifiable gaps; never fabricate them. A NO-GO is
a first-class result. Record what was tried, the mechanism, and what evidence or
changed condition would reopen it.
When the repository has adopted the journal as its durable design record, absorb
the durable goal, decisions, rationale, dead ends, and verification from temporary
specification or plan documents into the entry, then remove those temporary files
in the same PR. Do not rewrite unrelated historical design records.
Record Skill Use
Every entry ends with a roster of the skills invoked during the effort:
## Appendix: Skills Invoked
- `architecture-diagram` (beta) — build-time structure chart and one runtime chart.
- `technical-prose` — word-level pass over the caption text.
The roster covers the whole effort rather than the current session. On update,
append to it; do not rewrite it down to what this session remembers. List only
skills actually invoked. When the record is incomplete — compacted context, a
handoff, a resumed effort — say so in one line instead of inferring a plausible
list. An invented roster is worse than a short one, because a later survey
cannot tell the two apart. Omit the appendix when no skill was invoked.
A skill is beta when its own instruction text or its template manifest says so,
or when the user says so. Never infer immaturity from one bad result. Mark each
beta skill (beta) in the roster, name it in beta_skills, and give it a
subsection here:
## Skill Feedback
### architecture-diagram (beta)
- **Friction** — what was asked, which instruction misfired, what was done instead.
- **Confirmation** — a default that held under real use.
Record friction and confirmation both. A beta skill needs evidence that its
defaults survive contact, not only a complaint log. Every friction must name
what was asked, which instruction misfired, and what was done instead; drop an
item that cannot be stated that concretely. Omit the section, and beta_skills
with it, when no beta skill was invoked.
This record is advisory. Do not edit the beta skill, open an issue, or propose
an upstream change unless the user separately asks.
Operations
Open
Create the entry and index row. Capture goal, scope, evidence already known,
decision criteria where useful, intended approach, and current unresolved items.
For intent-first work, land this record before implementation.
Update
Re-read code, Git history, and durable evidence. Update updated, current
implementation, evidence, outcome, and unresolved items. Append newly invoked
skills to the roster and add any new beta-skill friction or confirmation. Paused
or blocked work remains open and names its blocker and restart condition.
Close
- For shipped work, set
status: shipped and record what landed, where, and how
it was verified.
- For a negative result, set
status: no-go and record the mechanism and reopen
condition.
- For replacement, set
status: superseded, add superseded_by, verify the
target exists, and explain the replacement.
Update updated, the index, and affected derived documents in the same change.
Reconcile
Scan journal markdown files except the index. Treat entry frontmatter as source
of truth and check:
status, opened, and updated exist.- Status is
open, shipped, no-go, or superseded.
updated is not earlier than opened.- A superseded entry names an existing replacement.
- A shipped entry carries implementation and verification evidence.
- A no-go entry carries its mechanism and reopen condition.
- Index date, title, status, and membership match the entries.
- Deferred and reopen items match an existing backlog.
beta_skills matches the subsections under ## Skill Feedback, and every
skill named there also appears in the roster.- An entry carrying
## Skill Feedback carries a non-empty beta_skills.
Entries written before the repository adopted the skill-use convention keep
their shape. Never backfill a roster or a feedback section by inference; a
survey cannot distinguish reconstructed history from observed history.
Repair mechanical index drift. For changes requiring judgment, report the exact
proposed edit before applying it. Preserve repository-specific headings and extra
frontmatter rather than rewriting mechanically.
Selectively reconcile existing backlog, roadmap, assumptions and limitations,
canonical fact sheets, datasets, and bibliographies only when materially affected.
Remove or close backlog items completed or deprecated by the outcome.
Report Possible Brief Inputs
Reconciliation may report, without creating vault artifacts:
- Problem framing candidate — durable problem, constraints, and evidence.
- Design reasoning candidate — approach, alternatives, and rationale.
For each candidate, name the entry and summarize why it qualifies. This is an
advisory handoff only. Do not invoke frame-problem. Do not invoke propose-design.
Do not create or update briefs unless the user separately asks
to start that workflow.
Index Template
# Engineering Journal
One durable, repository-local record per non-trivial effort. Entry frontmatter
is authoritative for lifecycle status.
| Opened | Effort | Status |
| --- | --- | --- |
| YYYY-MM-DD | [Effort title](YYYY-MM-DD-short-slug.md) | open |
Prose in an Entry
An entry outlives the effort it records, so its wording reaches someone with no
memory of the work. Follow technical-prose for word choice, including its
default of American spelling. A convention the repository states overrides that
default; a mixture of both states nothing.
Quoted evidence is exempt: a command, a log line, an error string, or a path is
copied exactly, whatever its spelling.
Stop Conditions
- Stop a lifecycle update when required evidence or a supersession target is
missing; state the gap.
- Ask one narrow question when repository conventions conflict and the answer
changes where or how records are written.
- Never use a GitHub issue, transient plan, or unmerged scratch file as the only
durable record of a non-trivial effort.
- Never silently create briefs during journal reconciliation.
