curate-project-context git:20261017.5b1062dA

Immutable. This exact content never changes and is served at /api/v1/blob/1380d493e1a3a5f1.

---
name: curate-project-context
description: Curates a project's public and private agent context. Use when checking context health, reorganizing accumulated guidance, repairing AGENTS.md or CLAUDE.md drift, finding stale, duplicated, misplaced or unreachable knowledge, or checking the public/private boundary.
---

# Curate Project Context

Keep the context system of a project coherent as it grows. Inspect public repository context,
private Brain knowledge, and the pointers between them; identify maintainability problems; then
apply only the repairs the user authorizes.

This skill has two modes:

- **Check** is the default. Diagnose and report without changing files.
- **Fix** applies findings the user explicitly asks to repair. An explicit request to organize,
  maintain, or fix the context authorizes repairs within the named project, but not lifecycle work
  owned by another skill.

## Scope limits

Fix mode writes files, so these bound what it may change:

- **Relocate settled facts, never adjudicate one.** A contested term or an unmade decision goes to
  `grill-decisions`; moving a fact is in scope, deciding it is not.
- **Report wiring, do not repair it.** `dotbrain doctor` supplies the mechanical baseline and
  `wire-brain` fixes it; use their evidence and route the repair.
- **Never touch another document's lifecycle.** Design closure and residue promotion are
  `close-design`'s; Beads state is `manage-work-graph`'s.
- **Credentials belong in the configured secret store**, never in public or private context files.

`write-agent-docs` supplies the writing discipline for pointers, hierarchy, completion criteria, and
pruning. Apply it when revising prose.

## Authority map

Classify each piece of project knowledge by its durable authority:

| Information | Authority |
|---|---|
| Task-specific retrieval and essential constraints | Public `AGENTS.md` |
| Established repository rules for making or reviewing changes | Tracked root `RULES.md`, routed from public `AGENTS.md` |
| Small private project rules and personal preferences | `.brain/AGENTS.md` |
| Shared Brain operations and private retrieval | `.brain/DOTBRAIN.md` |
| Private retrospective findings and evidence | `.brain/RETRO.md`, maintained by `run-retro` |
| Domain vocabulary | `.brain/CONTEXT.md` |
| Durable decisions and rationale | `.brain/adr/` |
| Initiative-specific working design | `.brain/designs/` |
| Execution status and work notes | Beads |
| Supporting explanation | A public or private referenced document chosen by sensitivity |

Public, private, and separately scoped `AGENTS.md` files retain their roles; each sibling
`CLAUDE.md` is a relative symlink to `AGENTS.md`. Keep private rules small and distinct from
repository requirements and shared operations. Public context remains useful without a Brain.
Public rationale stands on its own; private paths, record identifiers, and tracker state stay private.

## Check

### 1. Inventory the context surface

Read the nearest project instructions, then enumerate relevant public and private `AGENTS.md` and
`CLAUDE.md` files, including the private Brain's project rules.
If the project is wired, inspect `.brain/DOTBRAIN.md`,
`.brain/CONTEXT.md`, `.brain/project.yaml`, ADR and design indexes or frontmatter, and documents
reached by context pointers. Load full ADRs, designs, or supporting docs only when a finding requires
their content.

Run `dotbrain doctor` when available to establish the mechanical baseline. Report its wiring
findings separately from content-maintainability findings.

Completion: every context surface and pointer relevant to the project has a known location,
visibility, authority, and mechanical state.

### 2. Test topology and boundaries

Check that pointers resolve and required material is reachable under the condition that needs it.
Check that public, private, and separately scoped `CLAUDE.md` symlinks resolve to the
canonical sibling `AGENTS.md`.
Verify that public context still
works without a Brain, routes making and reviewing changes to root `RULES.md`, and contains
no private Brain material.

Completion: every broken link, weak pointer, invalid canonical relationship, and public/private
boundary violation is identified with its exact path and evidence.

### 3. Test authority and maintainability

Apply the authority map and `write-agent-docs` principles. Look for:

- the same meaning maintained by more than one authority;
- conflicting instructions or vocabulary across levels;
- stale guidance contradicted by the repository, configuration, or current Brain canon;
- easy environment lookups cached in prose without a useful convention, rationale, or hazard;
- knowledge stored in the wrong authority, including decisions or execution state in `AGENTS.md`;
- unreachable or orphaned documents, and pointers whose trigger does not name the branch that needs
  them;
- sprawling files whose branch-specific detail should be disclosed;
- private information in public context, or public operating knowledge hidden unnecessarily in the
  Brain.

Completion: each suspected problem is either supported by current evidence or discarded.

### 4. Report

Present findings in priority order:

| Finding | Evidence | Correct authority | Proposed repair | Owner |
|---|---|---|---|---|

Distinguish repairs this skill can apply from work routed to `wire-brain`, `grill-decisions`,
`close-design`, or `manage-work-graph`. A clean check says so and lists the surfaces examined.

Completion: every finding has an exact target and no proposed repair silently changes project
meaning or another document's lifecycle.

## Fix

Apply only the findings authorized by the user. Preserve meaning and useful history while moving a
fact to its authority, removing an exact duplicate, sharpening a pointer, pruning stale guidance,
or repairing an `AGENTS.md`/`CLAUDE.md` relationship. Back up a meaningful regular `CLAUDE.md`
before replacing it with a symlink.

After a move, update every pointer that should still reach the material. Keep public edits safe for
publication and scan the final public files for private Brain paths and identifiers. Re-run the
check against every changed surface and report any findings routed to other skills.

Completion: all authorized repairs are verified, unapproved findings remain untouched, and each
piece of moved knowledge has one reachable authority.

Keep personal preferences private even when they recur. Derive a public rule only when it is a
repository requirement that should apply to every contributor; recurrence alone does not make
a private preference public. Wiring and refresh preserve user-owned rules and notebooks.