Humans Tech Debt

Run recurring autonomous tech-debt reduction passes in this repository.

Start Or Resume

1. Confirm the repo root is the current Humans checkout.
2. Resume an existing techdebt/* worktree and branch if the user is continuing prior work.
3. Otherwise fetch origin/main, create a fresh branch techdebt/YYYY-MM-DD-codex-N, and attach a worktree at .claude/worktrees/techdebt-YYYY-MM-DD-codex-N.
4. Keep scratch notes and temporary files under local/tech-debt-runs/<run-id>/.

Non-Negotiable Limits

• Section-owned persistence and generated migrations are allowed when the task needs them. Follow section-migrations-in-maintenance; substantial architecture transitions get explicitly scoped tasks and dedicated PRs.
• Preserve JSON serialization contracts unless the task authorizes changing them.
• Removing or reshaping public members follows debt-sweep-standing-policy: dead members and pre-approved in-place shapes go; deleting files or controller actions still needs Peter.
• Prefer structural simplification and consolidation over broad rewrites.
• Treat Reforge or any score as a detector, not an objective. A score decrease alone never justifies a commit.
• Do not add thin behavior to DTO/request/command/options/input records just to escape a parameter-bag or long-signature rule. Methods such as ApplyTo, ToDto, RenderWith, BuildSummary, SaveAsync, or service-delegating wrappers are acceptable only when they enforce real invariants, validation, state transitions, or domain policy that the type already owns.

Working Loop

1. Read humans-tech-debt-rules.md.
2. Pick one high-value debt item at a time.
3. Before editing, write a one-sentence architecture thesis: what concept will be deleted, what responsibility will move to its rightful owner, or what duplication/coupling will disappear. If the thesis is "the score drops", abandon the candidate.
4. Make the smallest coherent improvement that reduces divergence, duplication, misplaced responsibility, or durable public surface.
5. Add or extend tests when practical.
6. Run targeted verification, plus dotnet build Humans.slnx --disable-build-servers -v q -clp:ErrorsOnly.
7. Run a score-blind second pass before commit. Review only the diff, the architecture thesis, and verification. Reject the change if it would not be worth keeping without metric movement.
8. Run the full dotnet test Humans.slnx --no-build --disable-build-servers -v quiet -clp:ErrorsOnly gate before any push.
9. Commit each accepted improvement separately and push the branch after verified progress.
10. Continue until remaining ideas are low-value, speculative, blocked by forbidden areas, or only reducible through metric-gaming changes.

Metric Integrity

• Use Reforge to find suspicious surfaces and compare checkpoints, not to decide that a weak patch is good.
• Prefer changes that remove a real concept, collapse duplicated behavior, narrow cross-section dependencies, or move a rule to its owning section.
• Reject refactors whose main effect is moving assignments, formatting strings, or service calls from one class into a request/command object without reducing coupling or clarifying ownership.
• Do not keep working toward a percentage target after the remaining candidates fail the architecture thesis or score-blind review. Report that the safe score reduction is exhausted instead.

Parallel Work

• Use subagents only for independent exploration or disjoint implementation slices.
• Keep ownership separated to avoid conflicting edits.
• Review and integrate each result before pushing.

Output

• Leave the worktree clean when stopping.
• Report the branch, worktree path, commits made, verification run, and any unresolved risks.