Compact map-resume skill body

[azalio]

Summary

• Move low-frequency /map-resume examples, state notes, token-budget notes, and troubleshooting into bundled resume-reference.md
• Keep the active recovery SKILL.md focused on checkpoint detection, briefing, confirmation, and continuation
• Add source/template regression coverage plus plan/done/learning updates for 2604.033-1

Validation

• pytest tests/test_skills.py::TestSkillStructure::test_map_resume_keeps_recovery_skill_body_compact tests/test_template_sync.py -v
• uv run --no-sync mapify init --no-git --mcp none, then inspected installed .claude/skills/map-resume/SKILL.md and resume-reference.md
• make lint
• pytest -m "not slow"
• pytest (attempted; timed out after 30 minutes without surfaced assertion output)

[Copilot]

Pull request overview

This PR restructures the /map-resume skill to keep the invoked SKILL.md compact for post-compaction recovery, moving low-frequency reference material into a bundled resume-reference.md. It also adds regression tests and documentation updates to prevent the skill body from regressing in size or losing the supporting reference.

Changes:

• Externalize /map-resume examples/technical notes/token budget/troubleshooting into resume-reference.md, keeping SKILL.md focused on the active recovery path.
• Add a skills regression test enforcing map-resume/SKILL.md size and presence/linking of the supporting reference for both .claude/skills and shipped templates.
• Update README/usage/architecture + improvement-plan loop documentation to reflect the compact recovery surface and follow-up slices.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_skills.py	Adds regression enforcing compact /map-resume skill body + supporting reference presence/linking (source + templates).
src/mapify_cli/templates/skills/map-resume/SKILL.md	Removes long appendices from invoked body; adds links to supporting reference for examples/troubleshooting.
src/mapify_cli/templates/skills/map-resume/resume-reference.md	New bundled appendix holding detailed examples, integration notes, token budget, troubleshooting.
.claude/skills/map-resume/SKILL.md	Mirrors the compacted /map-resume skill for the source-of-truth skills directory.
.claude/skills/map-resume/resume-reference.md	Mirrors the supporting reference appendix in the source-of-truth skills directory.
README.md	Documents the new “compact recovery surface” design for /map-resume.
docs/USAGE.md	Updates /map-resume section to mention the compact skill + supporting reference and branch-scoped checkpoint.
docs/ARCHITECTURE.md	Updates /map-resume architecture table/flow to reference step_state.json and the new reference file.
docs/learned/testing-strategies.md	Adds a learned rule to protect compact recovery skill bodies with regression coverage.
docs/learned/review-checks.md	Adds a learned review check for supporting-file externalization end-to-end.
docs/learned/commands.md	Adds a learned command to run the new /map-resume lifecycle regression tests.
docs/learned/architecture-patterns.md	Adds a learned architecture pattern about externalizing recovery appendices.
docs/improvement-plan.md	Records 2604.033-1 execution note + adds follow-on slices for broader skill compaction/linting.
docs/improvement-loop-log.md	Logs the 2604.033-1 change, validations, and reusable learnings.
docs/improvement-done.md	Marks 2604.033-1 as done and summarizes shipped changes + validations.

Comments suppressed due to low confidence (2)

src/mapify_cli/templates/skills/map-resume/resume-reference.md:182

• These troubleshooting steps instruct users to update step_state.json directly. Elsewhere the repo warns against direct JSON mutation because partial edits can leave current_step_phase/status inconsistent (e.g. .claude/skills/map-check/SKILL.md warns against jq/sed). Consider replacing this guidance with orchestrator-driven recovery (e.g., re-run resume_from_plan / resume_single_subtask, or explicitly document a safe, atomic repair path) so users don’t corrupt state.

**Fix:**

1. Manually verify each subtask's actual completion status
2. Update `step_state.json` to match reality
3. Resume from corrected state

.claude/skills/map-resume/resume-reference.md:182

• These troubleshooting steps instruct users to update step_state.json directly. Elsewhere the repo warns against direct JSON mutation because partial edits can leave current_step_phase/status inconsistent (e.g. .claude/skills/map-check/SKILL.md warns against jq/sed). Consider replacing this guidance with orchestrator-driven recovery (e.g., re-run resume_from_plan / resume_single_subtask, or explicitly document a safe, atomic repair path) so users don’t corrupt state.

**Fix:**

1. Manually verify each subtask's actual completion status
2. Update `step_state.json` to match reality
3. Resume from corrected state

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[azalio]

Fixed in 97847c2 by switching the example to the generic .map/<branch>/step_state.json path.

[azalio]

Fixed in 97847c2 by syncing the same generic .map/<branch>/step_state.json example into the source skill reference.

[azalio]

Fixed in 97847c2 by updating the adjacent security/manual recovery text to describe the current branch-scoped step_state.json checkpoint and call progress.md legacy where relevant.

[azalio]

Fixed in 97847c2 by updating the diagram and surrounding architecture wording from .map/progress.md/YAML parsing to .map/<branch>/step_state.json/orchestrator JSON parsing.