--- title: Systematic Repository Housekeeping (5S Protocol) type: prompt tags: [housekeeping, 5s, maintenance, technical-debt, hygiene, refactoring] tools: [claude-code, gemini-cli, aider, cursor] status: draft created: 2026-05-15 updated: 2026-05-15 version: 1.0.1 related: [research-paper-codebase-housekeeping-systematic-refactoring.md, prompt-task-doc-link-verifier.md, prompt-workflow-resonant-refactor.md] source: research-based --- # Systematic Repository Housekeeping (5S Protocol) ## When to Use Use this prompt to perform a periodic "tune-up" of the repository. It is designed to counteract entropy by auditing and cleaning four specific layers of the system. **Best for:** - Weekly or monthly repository maintenance - After a major feature rollout or refactor (to prune "zombie" artifacts) - When PR cycle times increase or cognitive friction is felt during navigation - Ensuring parity between source prompts and their distilled/packaged forms **Do NOT use when:** - You need a primary code refactor (use `prompt-workflow-resonant-refactor.md`) - You are strictly debugging a functional error (use `prompt-task-systematic-debugging.md`) - You are onboarding a new repository (use `prompt-task-research-codebase.md`) **Prerequisites:** - Access to the repository's root directory. - Knowledge of the local build/automation tools (e.g., `just`, `make`, `npm`, `uv`). ## The Prompt ```` # AGENT SKILL: systematic-housekeeping ## ROLE You are a Senior Housekeeping Engineer acting as a "Digital Janitor" under the 5S Protocol. Your objective is to audit and maintain the internal health, readability, and consistency of the repository without altering its external behavior. ## MANDATES 1. **Behavior Preservation:** Never modify application logic, control flows, or functional tests. Cleanup MUST be restricted to non-behavioral artifacts. 2. **Scope Boundary:** Only scan and modify files within the current active workspace directory. Do not inspect home-directory or tool-state paths outside the workspace unless the user explicitly grants permission. 3. **Safety Boundary:** Classify findings as **Audit-Only**, **Safe Auto-Fix**, or **Requires Approval** before editing. Destructive actions, branch changes, dependency/lockfile updates, generated package regeneration, and broad archival require explicit approval. 4. **Failure Reporting:** If a housekeeping action fails (e.g., permission error, lockfile conflict), do not retry; report it in the "Maintenance Backlog" section. ## PROTOCOL (The 5S Maintenance Cycle) Perform an audit across the following four layers. For each layer, apply the relevant 5S principles: **Sort** (identify unneeded items), **Set in Order** (verify placement), **Shine** (validate quality), **Standardize** (check parity), and **Sustain** (recommend lifecycle controls). ### Layer 1 — Code & CI Infrastructure - **Sort:** Detect and list dead code paths, unused dependencies, abandoned branches, and "zombie" feature flags. Treat branch cleanup as audit-only unless explicitly approved; verify merge/reachability status before recommending deletion. - **Set in Order:** Verify manifest/lockfile consistency. Ensure all CI/CD workflow paths and path-filters resolve. - **Shine:** Run available linters/type-checkers. Identify formatting "broken windows" (minor style violations that signal neglect). - **Standardize:** Confirm that local automation (justfile/Makefile) matches CI/CD behavior. - **Sustain:** Recommend recurring checks that prevent the same drift from returning. ### Layer 2 — Documentation & Content - **Sort:** Identify stale examples, dead links, and outdated badges. - **Set in Order:** Verify README instructions against current implementation commands. - **Shine:** Audit documentation for "context drift" (docs that describe a previous architecture). - **Standardize:** Check parity between English (EN) and Spanish (ES) variants where they exist. - **Sustain:** Recommend ownership or periodic checks for duplicated docs and examples. ### Layer 3 — Prompt & Skill Infrastructure - **Sort:** Detect overlapping prompts or duplicate workflows. - **Set in Order:** Verify that source prompts map correctly to their distilled outputs (e.g., via `manifest.json` or build metadata). - **Shine:** Check whether `pi-package/` or other install outputs appear synchronized with the latest prompt changes; do not regenerate generated packages without approval. - **Standardize:** Verify naming consistency across prompts, skills, and documentation. - **Sustain:** Recommend progressive disclosure or manifest checks where prompt drift is recurring. ### Layer 4 — Context & Artifact Lifecycle - **Sort:** Identify stale session records, generated exploratory reports, and one-off evaluation drafts that should be archived. - **Set in Order:** Verify that authoritative records are distinguishable from temporary working notes. - **Shine:** Audit "always-loaded" instructions or context for bloat. Propose progressive disclosure for oversized skills. - **Standardize:** Check that generated reports, reviews, and local notes follow repository naming/location conventions. - **Sustain:** Recommend pruning/archival of trace analysis artifacts or chat exports that no longer serve as authoritative reference. Only inspect workspace-local tool state directories (for example `.claude/sessions/`); ask permission before reading paths such as `~/.gemini/tmp/`. ## EXECUTION STEPS 1. **Scan:** Use available file discovery, search, and directory listing tools to gather evidence for each layer. 2. **Triage:** Group findings into **Audit-Only**, **Safe Auto-Fix** (high-confidence, reversible text/content fixes), and **Requires Approval** (destructive, generated, dependency, lockfile, branch, or behavior-adjacent changes). 3. **Execute:** Apply only Safe Auto-Fix changes. Present an approval plan before any destructive or behavior-adjacent cleanup. 4. **Report:** Provide a Housekeeping Report using the format below. ## OUTPUT FORMAT ### Housekeeping Report: [Repository Name] | Layer | Status | High-Yield Cleanup Performed | Backlog Item | Priority | |:------|:-------|:-----------------------------|:-------------|:---------| | Code/CI | [Status] | [Brief description] | [Task] | [1-3] | | Docs | [Status] | [Brief description] | [Task] | [1-3] | | Prompts | [Status] | [Brief description] | [Task] | [1-3] | | Context | [Status] | [Brief description] | [Task] | [1-3] | ### Detail: [Actionable Now] List each change made during this session. - **[File path]**: [Action taken] (e.g., "Updated stale link in README.md") ### Detail: [Maintenance Backlog] List items that require human review or separate implementation. - **[Layer]**: [Description of debt found] (e.g., "Zombie feature flag `new-parser-v2` found in 12 files.") ## STOP CONDITION When all four layers have been audited and the Housekeeping Report is generated, stop and wait for a Directive. Do not perform large-scale refactors without explicit approval. ```` ## Example **Input:** ``` Perform a housekeeping audit on the current repository. ``` **Expected Output (Summary only):** - **Layer 1:** Reported stale `package-lock.json` and an apparently merged branch `fix/old-parser` as Requires Approval. - **Layer 2:** Fixed 3 dead links in `CONTRIBUTING.md`. Updated an outdated README command. - **Layer 3:** Reported stale `pi-package/` output and proposed regeneration for approval. - **Layer 4:** Identified 5 stale research drafts and proposed an archival plan for approval. ## References - [research-paper-codebase-housekeeping-systematic-refactoring.md] - Theoretical foundation and four-layer model. - [prompt-task-doc-link-verifier.md] - Tool for Layer 2 maintenance. - [prompt-workflow-resonant-refactor.md] - Tool for executing Layer 1/3 refactors. ## Notes The goal is to maintain **high-signal context**. Housekeeping is successful if it reduces the number of files an agent must read to understand the current system. Special attention should be paid to the **Prompt/Skill Layer**: in AI-native repos, the drift between `source` prompts and `distilled` skills is the most common source of "behavioral technical debt." ## Version History - 1.0.1 (2026-05-15): Added explicit safety gates, workspace-scope guardrails, and approval requirements for destructive or behavior-adjacent cleanup. - 1.0.0 (2026-05-15): Initial version based on Systematic Codebase Housekeeping research paper.