stoa: Skill for Claude Code

Rewrite — $ARGUMENTS

Invoked when Edit (patch) is the wrong tool. Research shows search/replace fails 20-30% on evolved code, and accumulated failed patches poison the context (Liu et al. "Lost in the Middle"; Databricks Mosaic). See feedback_rewrite_after_fail.md.

When to use this skill

Triggered automatically via the hook post-edit-failure-tracker.sh at 2 consecutive Edit failures. Also invoke manually when:

• Diff estimated >30% of the file size
• Refactoring where structure changes, not just content
• File is small-to-medium (≤800 lines) and a clean rewrite is cheaper than hunting for correct search/replace anchors
• User says "just rewrite it"

Do NOT use for:

• Single-line changes (use Edit)
• Files >1500 lines (split first, or delegate to subagent)
• Files you haven't read yet in this session (read first, understand first)

Workflow

Step 1 — Parse arguments

Split $ARGUMENTS into:

• FILE_PATH (first token, absolute path)
• INTENT (remainder — what the rewrite should accomplish)

If INTENT is empty, ask the user: "What should the rewrite accomplish? (e.g. 'fix the auth middleware bug', 'add tenant filtering')". Do NOT guess the intent from context alone.

Step 2 — Read the current file

Always Read the full file before rewriting. If >1500 lines, stop and suggest splitting or subagent delegation instead.

Step 3 — Check pollution signal

jq --arg path "$FILE_PATH" '[.[] | select(.path == $path)] | .[0]' .claude/state/edit-attempts.json

If consecutive_fails ≥ 2, the rewrite is warranted. If total ≥ 5 but consecutive_fails < 2, consider whether a subagent with fresh context would be better than an inline rewrite (Main context already has noise).

Step 4 — Rewrite strategy

Preserve by default:

• Public API surface (exported symbols, function signatures if referenced elsewhere)
• Import structure and file-level conventions
• Comments that explain non-obvious WHY (delete comments that explain WHAT)
• Type annotations, docstrings where they exist