arminzou/dotbrain / plugin/skills/maintain-brain
maintain-brain
VerifiedCapture, update, check, and clean up private project understanding. Use when preserving useful context, revising a Brain record, checking drift or broken references, or removing obsolete and redundant Brain material.
Maintain Brain
Keep private project understanding accurate, reachable, and supported by evidence. These are record operations usable by any workflow. The selected workflow determines when capture happens and who performs it.
Authority and destinations
Read the nearest project instructions and the relevant existing records before writing. Capture information when later work needs understanding that existing sources do not adequately preserve, or when the user requests it. Session reasoning, easy lookups, and disposable experiments may stay temporary. Use the project's established vocabulary. The destinations below apply to material worth retaining; a task need not produce a record.
| Information | Destination | Reference to read for this operation |
|---|---|---|
| Settled domain terms and relationships | .brain/CONTEXT.md | Vocabulary |
| Adopted decisions whose rationale needs independent preservation | .brain/adr/ | ADR selection and decisions |
| Initiative intent, design, uncertainty, and outcome | .brain/designs/ | Designs and lifecycle |
| Verified findings, supporting sources, maintained explanations | .brain/docs/ | Findings and references |
| Work needing durable continuation or coordination, including agreed follow-up | Beads | Use work-graph for graph operations |
| Adopted public repository requirements and their routing | Repository RULES.md and AGENTS.md | Use repo-rules for public requirement changes |
Read Writing for agents when authoring agent-consumed prose. It includes placement guidance and the shared writing discipline.
Recording an observation does not adopt a decision. Distinguish:
- Observed: what a named source or check actually establishes, with its applicability.
- Inferred: an explanation drawn from evidence, with its reasoning and uncertainty.
- Hypothesis: an unresolved possibility and what would test it.
- Proposed: a suggested choice or requirement awaiting the applicable authority.
- Accepted: a choice adopted by the responsible person or established project authority, with the approval source and date.
Within an authorized capture, record needed facts and already approved decisions without repeated approval. Consequential new choices, contested meaning, and changes to scope, criteria, or authority require the applicable decision; preserve the unresolved question and supporting evidence when needed for continuation. Existing criteria remain intact. Current code proves behavior, not historical intent. Surface conflicts with accepted decisions rather than silently rewriting them to match implementation.
Retained private evidence and proposed improvements stay in private records or Beads.
repo-rules can derive standalone public wording from adopted requirements. A recurring
private preference alone does not establish a repository requirement. Never copy private
paths, identifiers, operational state, or sensitive evidence into public guidance; keep
credentials out of all records.
Capture or update
Use the destination's reference above. Prefer updating the appropriate existing record or linking its source over creating a parallel explanation. Keep the source, date or revision, applicability, and authority beside the claim they support. Link related records instead of duplicating their rationale. Missing evidence stays a named gap.
Preserve a useful conclusion with enough evidence to assess it. Keep its prototype or raw artifacts only when reproduction, consequential evidence, review, or unfinished work needs them. Preserving a conclusion does not require preserving every experimental variant.
Before saving, reread the current target and reconcile concurrent edits. Check numbering again when creating a numbered record; do not overwrite an existing file. If competing writes cannot be reconciled safely, preserve both contributions and report the conflict.
Completion: every captured claim has a fitting destination, distinguishable evidence and authority, and enough provenance for a later reader to assess or retrieve its source.
Check or clean up private context
For a check request, report findings without editing. For authorized maintenance, inspect the named records and their inbound and outbound pointers. Look for conflicting meaning, stale claims, duplicate authorities, misplaced execution state, broken links, weak retrieval conditions, and private information exposed publicly. Verify suspected drift against current evidence before changing it.
Within authorized cleanup, remove obsolete, redundant, or misleading material that no longer supports current understanding or unfinished work. Retain independently useful rationale and evidence where needed, and repair affected pointers. Historical interest alone does not require keeping a file; existing version history can provide recovery. Deletion need not produce a replacement summary.
Preserve unrelated user content and literal examples, active requirements, and existing
work state. User-authored material may be cleaned up when that material is within the
authorized scope. Reading a record does not itself require maintenance; ordinary work
does not trigger a Brain-wide cleanup. Report wiring problems for wire-brain; report public
requirement or routing changes for repo-rules.
Completion: authorized repairs resolve the supported findings, remaining pointers work, needed knowledge and unfinished work survive, and out-of-scope changes remain explicit.
Record lifecycle evidence
Use Designs and lifecycle for a design's terminal update. Document state describes initiative history; Beads remains the authority for task state. A terminal record requires evidence for its claimed outcome and the applicable authority. It does not itself accept work, close tasks, approve a PR, or authorize delivery.
Report
Name the records changed or checked, the material captured, and any unresolved decision, evidence gap, conflict, or proposed follow-up. Distinguish writing a record from verifying the behavior it describes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |