workflow-housekeep

# Repo Housekeep **Degree of freedom: MIXED.** What is dead vs still referenced `[HIGH freedom]`; delete-only-after-proof and dependency bump commands `[LOW freedom — run exactly]`. ## How to reason 1. **Observe** — README drift, unused files, outdated deps 2. **Interpret** — unused by search, or only unused in this package? 3. **Classify** — sync docs / delete / bump / leave 4. **Severity** — deleting a file still imported is a break ## Worked example > **Observe:** `OldButton.tsx` has zero imports; README still lists a removed script; patch bump available. > **Interpret:** file is dead; README is stale; bump is safe if tests pass. > **Classify:** delete the file after `rg` + import check; sync README; bump patch. > **Do not** delete `housekeep-design` token work — that is another skill. ## Self-critique before reporting - **Proven unused** — imports, refs, config, git history checked - **README matches** — scripts and paths in the README actually exist - **Tests after bump** — dependency update was not a silent break - **Right owner** — unused files/exports/deps → `plan-dead-code`; parked work → `housekeep-backlog`; token SSOT → `housekeep-design`; CI gates → `housekeep-gates` Full-cycle repository maintenance: documentation sync, dead file removal, dependency updates, and research-driven cleanup. Works with **any project** — auto-detects tech stack, package manager, and structure. ## Critical Rules [LOW freedom — do not skip] > **NEVER delete files without confirming they are truly unused.** > Check imports, references, git blame, and config entries before removing anything. > **NEVER blindly upgrade a major version.** > Major bumps may have breaking changes. Research the changelog before upgrading. > **README must reflect reality, not aspiration.** > Only document what currently exists in the codebase. > **Commit each phase separately.** > Documentation, cleanup, and dependency updates are independent concerns. > **Parked-work register is a different skill.** > Unfinished plans, TODOs, skipped tests → `housekeep-backlog`. This skill > does README / dead files / deps. A housekeep pass may *schedule* a > backlog regeneration; it does not invent the register. > **Module-graph dead code is a different skill.** > This skill deletes *artifacts* — logs, `.bak` files, build output, > committed screenshots — things dead by inspection. **Unused source > files, exports, types, and dependencies belong to `plan-dead-code` > (audit) and `housekeep-dead-code` (delete + ratchet)**, because proving > those dead needs a configured module graph, not a `rg` pass. --- ## Step 0: Auto-Detect Project Configuration [LOW freedom — run exactly] ### 0a. Detect Tech Stack Read the dependency manifest to determine the ecosystem: | File | Ecosystem | Package Manager | |------|-----------|-----------------| | `package.json` + `package-lock.json` | Node.js | npm | | `package.json` + `pnpm-lock.yaml` | Node.js | pnpm | | `package.json` + `yarn.lock` | Node.js | yarn | | `package.json` + `bun.lockb` | Node.js | bun | | `requirements.txt` / `pyproject.toml` | Python | pip / poetry / uv | | `Cargo.toml` | Rust | cargo | | `go.mod` | Go | go mod | | `Gemfile` | Ruby | bundler | | `build.gradle` / `pom.xml` | Java/Kotlin | gradle / maven | | `pubspec.yaml` | Dart/Flutter | pub | | `composer.json` | PHP | composer | ### 0b. Detect Project Structure ``` Glob("README*") Glob("**/*readme*") Glob("**/CHANGELOG*") Glob("**/.env*") Glob("**/*.log") Glob("**/dist/**") Glob("**/build/**") Glob("**/*.screenshot*") Glob("**/*.png", in test/debug/temp folders) ``` ### 0c. Record Configuration ``` ECOSYSTEM: [Node.js / Python / Rust / Go / etc.] PKG_MANAGER: [npm / pnpm / yarn / bun / pip / poetry / cargo / etc.] MANIFEST: [package.json / requirements.txt / Cargo.toml / etc.] LOCKFILE: [package-lock.json / yarn.lock / etc.] README_PATH: [README.md or detected path] SRC_DIR: [src/ / app/ / lib/ / etc.] BUILD_DIR: [dist/ / build/ / .next/ / out/ / etc.] FRAMEWORK: [Next.js / React / Vue / Django / FastAPI / etc.] ``` --- ## Phase 1: README Sync [HIGH freedom] Update the root README (and any folder-level READMEs) to reflect the **current** architecture. ### 1a. Discover Current Architecture Read these files to understand what actually exists: ``` - Package manifest (package.json, etc.) — dependencies, scripts, name, description - Entry point (src/index.ts, app/layout.tsx, main.py, etc.) - Config files (next.config.*, vite.config.*, tsconfig.json, etc.) - CI/CD (.github/workflows/*, vercel.json, netlify.toml, Dockerfile, etc.) - Environment files (.env.example, .env.local) — list expected env vars - Folder structure (top-level ls, then 2-level deep ls of src/) ``` ### 1b. Cross-Check README Against Reality For each section in the existing README, verify: | README Section | Verify Against | |---------------|----------------| | Project description | `package.json` name/description, actual functionality | | Tech stack | Installed dependencies in manifest | | Getting started / Setup | Actual scripts in `package.json`, required env vars | | Folder structure | Real directory listing | | API endpoints | Route files, API handlers | | Features list | Actual implemented features (not planned/removed) | | Environment variables | `.env.example` or config files | | Deployment | CI/CD config, hosting config | | Contributing | Linter config, test setup, pre-commit hooks | ### 1c. Rewrite Stale Sections For each discrepancy found: - **Missing feature in README**: Add it with accurate description - **Removed feature still in README**: Delete the section - **Outdated instructions**: Update to match current setup - **Missing sections**: Add standard sections (see template below) ### 1d. README Template (adapt to project) Use the README skeleton in [`references/templates.md`](references/templates.md) and adapt each section to the detected stack. ### 1e. Folder READMEs Check for any `*_readme.md` or `README.md` files in subdirectories. Update them if the folder contents have changed. --- ## Phase 2: Dead File Cleanup [LOW freedom — run exactly] Remove files that serve no purpose in the repository. ### 2a. Scan for Candidates Search for these categories of dead files: **Logs and debug output:** ``` Glob("**/*.log") Glob("**/npm-debug.log*") Glob("**/yarn-debug.log*") Glob("**/yarn-error.log*") Glob("**/debug.log") Glob("**/.pnpm-debug.log*") ``` **Screenshots and temp images:** ``` Glob("**/screenshot*") Glob("**/Screenshot*") Glob("**/*.png", in root or non-asset directories) Glob("**/*.jpg", in root or non-asset directories) Glob("**/temp/**") Glob("**/tmp/**") ``` **Build artifacts committed by mistake:** ``` Glob("**/dist/**") Glob("**/build/**") Glob("**/.next/**") Glob("**/node_modules/**") Glob("**/__pycache__/**") Glob("**/*.pyc") Glob("**/target/debug/**") (Rust) ``` **Deprecated / dead code:** ``` Glob("**/*.bak") Glob("**/*.old") Glob("**/*.orig") Glob("**/*deprecated*") Glob("**/*DEPRECATED*") Glob("**/*.backup") Glob("**/*_old.*") Glob("**/*_backup.*") Glob("**/*.tmp") ``` **IDE and OS artifacts:** ``` Glob("**/.DS_Store") Glob("**/Thumbs.db") Glob("**/*.swp") Glob("**/*.swo") ``` **Stale config files:** ``` Glob("**/.env.local") (should not be committed) Glob("**/.env.production") (check if contains secrets) ``` ### 2b. Validate Before Deleting For each candidate file: 1. **Check git blame**: When was it last modified? By whom? 2. **Check imports/references**: Is any code importing or referencing this file? ``` Grep for the filename across the codebase ``` 3. **Check .gitignore**: Should this file type already be ignored? 4. **Check CI/CD**: Does any workflow reference this file? **Classification:** | Category | Action | |----------|--------| | Log files | Delete + add to `.gitignore` | | Screenshots in non-asset dirs | Delete (or move to docs/ if referenced) | | Build artifacts | Delete + verify in `.gitignore` | | `.bak` / `.old` / `.orig` files | Delete (git has history) | | IDE/OS artifacts | Delete + add to `.gitignore` | | Secret files committed | Delete + rotate secrets + add to `.gitignore` | | Deprecated code files | Verify unused → delete | ### 2c. Update .gitignore After cleanup, ensure `.gitignore` prevents reoccurrence: ``` Check existing .gitignore covers: - logs/ *.log - build output dist/ build/ .next/ out/ - env files .env.local .env.production - OS files .DS_Store Thumbs.db - IDE files .idea/ .vscode/ (unless project uses shared settings) - temp files *.tmp *.bak *.swp - dependencies node_modules/ __pycache__/ target/ ``` ### 2d. Dead Exports / Unused Code → hand off **Do not run a dead-code sweep from this skill.** Unused source files, exports, types, and dependencies are a module-graph question: on a first run most findings are misconfiguration, and deleting them is how a cleanup becomes an outage. | Stack | Owner | |-------|-------| | TypeScript / JavaScript | `plan-dead-code` → `housekeep-dead-code` (`/deadcode`) | | Python | `vulture` — same discipline: baseline and review before deleting | `ts-prune` is in maintenance mode; its author points to Knip. Do not add it to a project. What this skill still owns here: noting that the handoff is needed, and scheduling it. Record the finding and move on. --- ## Phase 3: Dependency Updates [HIGH freedom] ### 3a. Audit Current State **Node.js:** ```bash npm outdated # see what's behind npm audit # check vulnerabilities ``` **Python:** ```bash pip list --outdated pip-audit # or safety check ``` **Rust:** ```bash cargo outdated cargo audit ``` **Go:** ```bash go list -m -u all govulncheck ./... ``` ### 3b. Classify Updates | Update Type | Risk | Action | |-------------|------|--------| | Patch (1.2.3 → 1.2.4) | Low | Auto-update | | Minor (1.2.3 → 1.3.0) | Low-Medium | Auto-update, verify build | | Major (1.2.3 → 2.0.0) | High | Research changelog first |