notebook-hygiene

Notebook Hygiene

Purpose

Restore a project notebook to a small, predictable working set without losing active work, durable rationale, or lifecycle-managed records. Treat cleanup as an information-architecture task, not a bulk deletion exercise.

Entry Conditions

1. Identify one explicit target notebook. If the user did not name one, ask before continuing.
2. Read the repository instructions and local notebook guidance first. Prefer AGENTS.md, the root README, and files such as documentation/agents/notebook.md when present.
3. Use the nb MCP tools for notebook operations. Notebook selectors are not repository filesystem paths.
4. Do not inspect or modify other notebooks merely because the target notebook references them.
5. If the user requested an audit or assessment, do not mutate anything. If the user explicitly requested cleanup, apply only unambiguous changes and present ambiguous cases together for a decision.

For a non-trivial cleanup, track the audit, classification, mutation, and verification phases with the session task-list tool.

Audit

Build the inventory before changing anything:

1. List top-level folders and root-level items.
2. List child folders and their contents. Follow the depth allowed by local policy; do not assume every notebook uses the same component names.
3. Inventory open and completed todos. Confirm todo state from [ ] and [x] rather than decorative item glyphs.
4. Inspect candidate stale records, including old handoffs, completed reviews, resolved issues, session notes, test notes, root-level notes, and duplicated trackers.
5. Search for status tags, old selectors, references to completed trackers, and notes hidden at a category root alongside component subfolders.
6. Read each candidate before classifying it. Titles and age alone are not enough evidence for deletion.

Classify each candidate into one of these groups:

Class	Treatment
Active	Keep in the local issue-type/component taxonomy.
Lifecycle-managed	Leave in place and use its owning workflow or CLI.
Durable history	Move to artifacts/<component> or the local equivalent.
Procedure	Move to procedures/<component> or the local equivalent.
Completed	Delete when the outcome is preserved in code, tests, releases, or durable documentation.
Stale or duplicate	Delete after confirming that no unique action or rationale remains.
Ambiguous	Preserve and ask one bundled clarification question.