diff --git a/.agents/skills/memory-hygiene/SKILL.md b/.agents/skills/memory-hygiene/SKILL.md new file mode 100644 index 00000000000..ce0f3f2612c --- /dev/null +++ b/.agents/skills/memory-hygiene/SKILL.md @@ -0,0 +1,67 @@ +--- +name: memory-hygiene +description: >- + Agent-only discipline for keeping firstmate's private memory lean and robust. + Use before writing, rewriting, pruning, deduplicating, or otherwise leaning entries in data/captain.md or data/learnings.md. +user-invocable: false +metadata: + internal: true +--- + +# memory-hygiene + +Keep each private-memory entry at the essence of what future firstmate sessions need to act correctly. +This skill owns entry shape for `data/captain.md` and `data/learnings.md` only. +`AGENTS.md` section 6 owns knowledge routing and the files' inspect-then-update, rewrite-in-place contract. +The `/stow` skill owns session sweeps, and `firstmate-coding-guidelines` owns repository-wide knowledge placement and one-owner discipline. + +## Entry standard + +- Record only the actionable rule or durable fact. +- Strip emotion, emphasis, interpersonal interpretation, and incident drama. +- Do not preserve that anyone was furious, shocked, disappointed, emphatic, or otherwise emotionally affected. +- Preserve the operational instruction or evidence-backed fact that remains after the mood is removed. +- Limit an entry to the rule or fact plus, at most, a one-line example or a `[[pointer]]` to its detailed source. +- Put incident chronology, rationale, logs, and supporting narrative in their proper detailed source, not private memory. +- Apply `firstmate-coding-guidelines`' one-owner rule when deduplicating memory. +- Fold a new lesson into the existing entry it sharpens instead of adding a near-duplicate. +- Rewrite or prune the owning entry in place so the file converges instead of growing as a log. + +## Update practice + +1. Use `AGENTS.md` section 6 to confirm that the knowledge belongs in one of these private-memory files. +2. Inspect the current file and the candidate owning entry before writing. +3. Search nearby entries for overlap, stale wording, and superseded variants. +4. Reduce the new information to one actionable rule or durable fact. +5. Rewrite the existing owner when one exists; add a new entry only when no owner exists. +6. Remove superseded or duplicate wording in the same update. +7. Read the result once more and cut any detail that does not change future action. + +Use a one-line example only when the rule would otherwise be ambiguous. +Use a `[[pointer]]` when a future session may need evidence or context beyond the essence. +Do not use either device to smuggle a narrative back into the memory file. + +## Before and after + +Before: + +> 2026-07-22: The captain was furious after an agent tried to deploy while checks were failing, and stated very firmly that this was completely unacceptable because the incident wasted hours and created a stressful rollback. + +After: + +> Require green CI before deployment. `[[deploy-incident-2026-07-22]]` + +The rewrite retains the future action and a route to evidence. +It drops mood, drama, chronology, and commentary that do not change the rule. + +## Final check + +Reject the update if any answer is yes: + +- Does it describe emotion or intensity instead of changing future action? +- Does it retell an incident beyond one short example or pointer? +- Does another entry already own the same rule or fact? +- Could the existing owner be sharpened instead of adding a new entry? +- Did the file grow without stale or duplicate wording being considered? + +Private memory is a curated operating aid, not an incident log. diff --git a/AGENTS.md b/AGENTS.md index b0cbb7d6c6e..87db5fe2039 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -331,13 +331,15 @@ Route each piece of durable knowledge to its most specific home: | Kind of knowledge | Home | | --- | --- | -| Captain preferences and working style | `data/captain.md`, inspected first and rewritten or pruned in place | +| Captain preferences and working style | `data/captain.md`, inspected first, kept as deduplicated rule-only essence with no drama, and rewritten or pruned in place | | Project-intrinsic knowledge | that project's own `AGENTS.md`, via normal crewmate delivery, never hand-written by firstmate | -| Fleet-local facts and gotchas only: load-before-doing procedures are skills; be-aware background is a learning; when in doubt, use a skill | `data/learnings.md`, inspected first and rewritten or pruned in place | +| Fleet-local facts and gotchas only: load-before-doing procedures are skills; be-aware background is a learning; when in doubt, use a skill | `data/learnings.md`, inspected first, kept as deduplicated fact-only essence with no drama, and rewritten or pruned in place | | Knowledge generalizable to every firstmate user | the shared `AGENTS.md`, shipped via PR through the pipeline | | Task-scoped notes | backlog item notes, inspect first with `tasks-axi show --full`, then replace the body with `tasks-axi update --body-file `, adding `--archive-body` when superseded prior state should remain recoverable, or hand-edit per the active backend | | Investigation findings | scout reports at `data//report.md` | +Load `memory-hygiene` before writing or leaning `data/captain.md` or `data/learnings.md`; it owns the per-entry leanness standard while this section owns routing. + When the captain invokes `/stow`, load the `stow` skill. It sweeps the current session for uncaptured durable knowledge, routes findings with this table, files undone next steps to the backlog, and reports whether the session is safe to reset. @@ -783,6 +785,7 @@ These skills are not captain-invocable; they are conditional operating reference - `firstmate-codexapp` - load before coordinating a visible Codex Desktop thread, evaluating a Codex App backend request, or reconciling Codex Desktop host-tool smoke evidence for Firstmate work. - `skill-authoring-standard` - load before authoring or substantially editing any skill in this repo or any project, and before briefing a project crew to do so. - `firstmate-coding-guidelines` - load before changing firstmate's shared, tracked material, as defined by section 1's list, whether editing directly or briefing a crewmate for a firstmate-repo task. +- `memory-hygiene` - load before writing, rewriting, pruning, deduplicating, or otherwise leaning `data/captain.md` or `data/learnings.md`. - `lavish-decision-boards` - load before creating or revising a captain-facing Lavish board that asks the captain to make decisions or provide structured feedback. - `eks-usage` - load before running `kubectl` or Amazon EKS commands, on an EKS IAM, authenticator, TLS, or connectivity error, or whenever the active cluster or context is uncertain.