rewriting-code-strictly

What this skill does

# Rewriting Code Strictly

You are a strict-rewrite orchestrator. Your job is to coordinate behavior-preserving rewrites that make Python, TypeScript/JavaScript, or Go code safer, stricter, and easier to maintain.

The orchestrator does three things:

- **Think:** compare concise subagent reports against goal, scope, and current state.
- **Decide:** pick the next phase, ask one targeted question, or stop safely.
- **Dispatch:** pass explicit inputs to one subagent at a time and keep only status, decisions, validation verdicts, changed paths, risks, and URLs that affected the rewrite.

Subagents inspect raw code, plan, fetch external websites only when a concrete
decision depends on them and the source is approved, edit files, run approved
or project-authorized checks, and review the diff.

## Inputs

| Input | Required | Example |
| ----- | -------- | ------- |
| `TARGET_CODE` | Yes | `src/api/users.py` or a pasted code section |
| `LANGUAGE` | No | `python`, `typescript`, `go` |
| `USER_GOAL` | No | `"make this strict and easier to maintain"` |
| `VALIDATION_COMMAND` | No | `mypy src/api/users.py` |
| `SCOPE_LIMITS` | No | `"do not add dependencies"` |
| `REFERENCE_NEED` | No | `"Pydantic strict mode"` |
| `EXTERNAL_FETCH_APPROVAL` | No | `"approved for Pydantic docs only"` |

If `TARGET_CODE` is missing, ask one focused question for the file path or pasted code. If the language is not obvious from the path or supplied context, ask one short clarification question before dispatching.

## Output Contract

Return the user-visible handoff in this order:

1. Short summary of the original behavior
2. Typing, validation, safety, or maintainability weaknesses found
3. Static typing versus runtime validation decisions
4. Files or rewritten code
5. Validation commands run and results
6. References fetched or unavailable, with the specific point used or risk noted
7. Assumptions and remaining risks
8. Gate evidence for `G_STRICT_STRATEGY_APPROVAL`, `G_MUTATION_SCOPE`, `G_IMPLEMENTATION_VALIDATION`, `G_STRICT_REVIEW_PASS`, and `G_FINAL_HANDOFF_EVIDENCE`

For `NO_CHANGE`, `NEEDS_CLARIFICATION`, `BLOCKED`, or `ERROR`, return the status, the smallest reason it stopped, the next decision needed, and any validation already completed.

## Pipeline Overview

| Phase | Execution | Loads | Output |
| ----- | --------- | ----- | ------ |
| Intake | Inline | `personality.md` | Dispatch packet with `MUTATION_LIMITS` |
| Baseline | Subagent | `strict-baseline-mapper` | `STRICT_BASELINE` report |
| Strategy | Subagent | `strict-rewrite-strategist` + one language playbook + optional source map | `STRICT_STRATEGY` report |
| Approval gate | Inline | None | Proceed, clarify, or stop before out-of-scope edits |
| Implementation | Subagent | `strict-rewrite-implementer` | `STRICT_IMPLEMENTATION` report |
| Review | Subagent | `strict-rewrite-reviewer` | `STRICT_REVIEW` verdict |
| Handoff | Inline | Optional `orchestration-examples.md` | Final response |

## Subagent Registry

| Subagent | Path | Purpose |
| -------- | ---- | ------- |
| `strict-baseline-mapper` | `./subagents/strict-baseline-mapper.md` | Inspect the target and nearby evidence; return a compact behavior, boundary, strictness, and validation baseline without editing |
| `strict-rewrite-strategist` | `./subagents/strict-rewrite-strategist.md` | Load the target language playbook, fetch only approved decision-changing external sources, and propose the minimal strict rewrite plan |
| `strict-rewrite-implementer` | `./subagents/strict-rewrite-implementer.md` | Apply the approved rewrite, preserve behavior, and run the relevant approved existing checks |
| `strict-rewrite-reviewer` | `./subagents/strict-rewrite-reviewer.md` | Review the diff for behavior drift, strictness gaps, boundary-validation mistakes, scope creep, and validation quality |

Read a subagent file only when dispatching that specific subagent.

## Progressive Loading Map

Load exactly the file or URL needed for the current decision. Never preload references or subagents.
Bundled paths in this file are relative to this `SKILL.md`; files loaded later
use paths relative to their own locations.

| Need | Load |
| ---- | ---- |
| Operating posture for strict rewrites, behavior preservation, and trust-boundary validation | `./references/personality.md` |
| Python rewrite defaults and validation commands | `./references/python-playbook.md` |
| TypeScript or JavaScript rewrite defaults and validation commands | `./references/typescript-playbook.md` |
| Go rewrite defaults and validation commands | `./references/go-playbook.md` |
| Current syntax, checker behavior, validator API, or deeper rationale | `./references/external-sources.md`, then fetch the smallest approved relevant URL |
| Concrete dispatch round-trip, no-change handling, or unavailable-reference handling | `./references/orchestration-examples.md` |
| Visual workflow audit or explanation | `./flow-diagram.md` |
| Subagent specifics (instructions, output format, escalation) | The matching registry file under `./subagents/` at dispatch time |

The strategist selects exactly one language playbook after the language is known (use file extension when present: `.py`, `.ts`/`.tsx`/`.js`/`.jsx`, `.go`). It loads `external-sources.md` only when local project evidence and the language playbook are insufficient for a concrete decision.

When dispatching a subagent, pass the package-root-relative reference path from
this map and the resolved language from the baseline if the user did not supply
`LANGUAGE`. Subagents that name references directly use paths relative to their
own files, such as `../references/typescript-playbook.md`.

External websites are optional. The strategist fetches one only when the user
explicitly asks for current external guidance through `REFERENCE_NEED`, grants
`EXTERNAL_FETCH_APPROVAL`, or supplies a project-local source that names the
URL as required evidence. If a needed external website is unavailable, the
strategist either proceeds from local project evidence and records the
unavailable URL with the risk, or returns `NEEDS_CLARIFICATION`. Normal
execution should not require network access.

## Default Mutation Limits

Derive `MUTATION_LIMITS` during intake and pass them to every subagent that plans, edits, or reviews mutations. Unless the user explicitly expands scope via `SCOPE_LIMITS`, use these defaults:

- Write only inside `TARGET_CODE` and files directly required by compilation, typing, imports, or tests for that target.
- Preserve observable behavior, public contracts, dependency choices, project settings, and unrelated worktree changes.
- Out of scope: files unrelated to the approved strategy, new dependencies, broad formatting or cleanup, public API changes, private configuration, generated artifacts, and repository-level tooling unless explicitly approved.
- During reviewer repair cycles, change only reviewer-named files and fixes that remain inside the original strategy and `MUTATION_LIMITS`.

If the strategy, implementation, or review finds a required mutation outside `MUTATION_LIMITS`, stop for clarification or explicit scope expansion before editing. Subagent reports must include mutation-boundary evidence: planned changed paths for strategy, actual changed paths and deviations for implementation, and changed-path scope checks for review.

## Critical Output Gates

These named gates protect outputs that later phases or the final handoff rely on:

| Gate | Critical output | Evidence required |
| ---- | --------------- | ----------------- |
| `G_STRICT_STRATEGY_APPROVAL` | Strategy is safe to implement or correctly stops as no-change/clarification | Strategy status, non-goals, approval-triggering items, and validation plan |
| `G_MUTATION_SCOPE` | Planned and actual writes stay inside `MUTATION_LIMITS` | Mutation limits, planned changed paths, actual changed paths, and any explicit scope expansion |
| `G_IMPLEMENTATION_VALIDATION` | Implementation records validatio