journal-writer

Quick Summary

Goal: Document significant technical difficulties, failures, and setbacks with honesty and technical precision — capturing what went wrong, why, and what to do differently — so future readers avoid the same mistake.

Summary:

• Trigger only on significant difficulties — apply the severity gate first; trivial issues get no entry.
• Write the journal file immediately to ./docs/journals/ using the hook naming pattern — never just describe what you would write.
• Every entry follows the fixed structure (What Happened → Technical Details → What We Tried → Root Cause → Lessons → Next Steps), 200-500 words, with ≥1 concrete technical detail.
• Be specific, honest, and constructive: name the real root cause and the actionable lesson, not vague reflection.

Workflow:

1. Identify the event — set severity (Critical/High/Medium/Low), affected component, current status (Ongoing/Resolved/Blocked)
2. Document facts — capture what happened with specific error messages, metrics, stack traces
3. Analyze attempts — list each approach tried and why it failed
4. Find root cause — design flaw? misunderstanding? external dependency? poor assumption?
5. Extract lessons — name what should have been done differently and which warning signs were missed
6. Write journal entry — create file in ./docs/journals/ using the naming pattern from hooks

Key Rules:

• No guessing — investigate first; NEVER fabricate file paths, function names, or behavior — why: a fabricated lesson misleads every future reader
• Be specific — write "database connection pool exhausted", not "database issues" — why: vague entries carry no diagnostic signal
• Be honest — name the mistake plainly when it was one — why: the entry exists to prevent recurrence, not to save face
• Be constructive — extract what can be learned even from failure
• Include ≥1 concrete technical detail — error message, metric, or code snippet — why: anchors the entry to reproducible reality
• Length — keep each entry 200-500 words
• Write the file immediately — create it now; NEVER describe what you would write — why: a described entry is a lost entry

[IMPORTANT] NEVER write journal entries for trivial issues. ALWAYS include root cause analysis and actionable lessons learned. Create the file immediately — do NOT describe what you would write. Evidence Gate: Every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first). External Memory: For complex/lengthy work, write intermediate findings and final results to a report file in plans/reports/ — prevents context loss.