bm-writing

# Write Useful Project Memory Use this shared standard whenever a Codex Basic Memory skill writes or substantially revises a note. This file is intentionally user-customizable: edit the voice, emphasis, and preferred structure here to fit how you want to remember your work. Task-specific skills still own required metadata, schemas, evidence gathering, and workflow. This skill shapes the note; it never overrides factual constraints. ## Voice - Write for a human or agent returning later and trying to understand what happened. - Be clear, direct, warm, and technically honest. - Prefer concrete observations over generic praise. - Have a point of view when the evidence supports it. It is fine to call a change elegant, messy, risky, boring, or satisfying when you explain why. - Keep personality in service of memory, not performance. ## Tell The Story - Give the note a narrative spine: problem -> approach -> current state and impact. - Explain why the approach works, how the system or workflow changed, and why that difference matters. - Name relevant tradeoffs, sharp edges, useful simplifications, removals, and intentionally parked work. - Prefer exact behavior, component names, paths, and commands over phrases such as "made progress" or "updated the implementation." - Use substantive prose for context and reasoning. Do not reduce the note to a wall of bullets or a commit-by-commit changelog. - Name the durable lesson when one exists — the constraint discovered, the boundary made explicit, the shortcut future work should avoid. That is the part that turns a status report into project memory. - Match depth to the subject. A small remembered fact should remain small. ## Anchor The Work - When the note records repository work, capture where that work lives: the project or repo, the git branch, and the PR or issue — plus the commit sha when a specific commit matters. - Put anchors the note's schema defines in frontmatter; record the rest as observations, e.g. `- [branch] feat/bm-writing` or `- [pr] #1123`. - Render GitHub-backed PR, issue, and commit anchors as Markdown links when their canonical URLs are verified. Keep local or unpushed SHAs as code instead of constructing links that may not exist. - Only anchor what is relevant. A remembered fact with no repo context needs no git anchors at all. ## Preserve The Semantic Layer - Distill durable facts under `## Observations` as `- [category] fact`. - Record decisions as `[decision]` observations, not plain bullets in a separate Decisions section. - Put graph edges under `## Relations` using `- relation_type [[Target Note]]`. Never represent a relation as an observation such as `[relates_to]`. - Add relations when they clarify context; do not manufacture targets merely to make a note look connected. ## Evidence Boundary - Do not invent intent, impact, verification, decisions, or drama. - State uncertainty and missing evidence plainly. - Never claim a test or deployment passed unless it ran or the user supplied the result.