| name | source-command-finding |
| description | Append a dated finding to dev/_journal/journal.md using the canonical template. Captures non-obvious behaviors, bug root causes, and durable insights for future sessions. |
source-command-finding
Use this skill when the user asks to run the migrated source command finding.
Command Template
/finding — Record a Durable Finding
Primary references:
When to Record
Record a finding when ALL of these are true:
- The fact is non-obvious — a reader of the code alone would not infer it.
- The fact is durable — it will still be true in a week, a month, a year.
- The fact has reusable value — another agent or contributor would benefit.
Do NOT record:
- Run-of-the-mill refactoring notes.
- Step-by-step implementation logs.
- Personal opinions.
- Anything already in
docs/QUICK_REFERENCE.md, docs/GOVERNANCE.md, a skill, or a rule (link instead).
Workflow
1. Open the Template
Read dev/_journal/FINDING_TEMPLATE.md. Copy its block.
2. Fill In the Fields
- Date prefix:
[YYYY-MM-DD Europe/Brussels] — today's date in the repo's canonical timezone.
- Title: one short sentence summarizing the finding.
- Context: what you were doing when the finding emerged (1-3 sentences).
- Symptom / Observation: the surprising behavior or fact (1-3 sentences).
- Root Cause: why it happens, traced to specific files and lines.
- Resolution: what you did about it, or what you would recommend.
- Why This Matters for Future Work: the reusable insight.
- References:
file:line anchors, related docs, PRs, commit SHAs.
- Promotion Consideration: which of the 5 destinations (if any) this entry should graduate to eventually.
3. Append to the Journal
Open dev/_journal/journal.md. Append the filled-in block at the end. Leave exactly one blank line between entries.
Do NOT:
- Insert in the middle (chronological order only).
- Delete or edit prior entries (annotate them instead — see PROMOTION_RULES).
- Create a new
.md file for a single finding.
4. Cross-Reference (optional)
If the finding closes a bug that a test should catch, add a comment in the test linking to the journal line. If it documents a pattern, consider opening an intent in .Codex/contract/intents.yaml or a rule in .Codex/rules/.
Anti-Patterns
- ❌ Recording "I learned how to use
dotnet test." (Not non-obvious.)
- ❌ Recording "This field is a string." (Not durable / not reusable.)
- ❌ Recording a finding that contradicts QUICK_REFERENCE without first updating QUICK_REFERENCE.
- ❌ Deleting old journal entries. They remain even after promotion — add a
→ promoted to X annotation instead.
- ❌ Logging an entry without the
[YYYY-MM-DD Europe/Brussels] prefix.
Promotion Cadence
When an entry has been referenced by ≥2 subsequent entries, cited in a PR review, or generalizes beyond its original feature — it's a candidate for promotion. See dev/_journal/PROMOTION_RULES.md.
Related
