Skip to content

feat: /apple:debt — measure and pay down an existing app's own debt - #108

Merged
rshankras merged 2 commits into
mainfrom
feat/102-debt
Nov 4, 2026
Merged

rshankras merged 2 commits into
mainfrom
feat/102-debt

Conversation

@rshankras

Copy link
Copy Markdown
Owner

Closes #102.

What

New command /apple:debt [area | rule-set] [--report]: it measures an existing app against the rules SwiftShip already enforces on new work, and pays the debt down safely. modernize keeps the app current with Apple; debt pays down the app's own debt.

  1. Measure. Lints with the project's .swiftlint.yml plus the skills' fragments, passed as extra --config files so nothing in the project changes:
    • fragments: design/design-system, swift/code-size, swift/concurrency, ios/coding-best-practices
    • counts only those rules, per area (folder) and rule set
    • adds map's design-debt score and missing-font check, per-area test presence, the coverage baseline, and concurrency warnings when a build log is at hand
  2. Prioritize. Priority is violations × (commits in the last 6 months + 1).
    • The top 3–5 areas get paid down.
    • Areas untouched for 6 months are frozen in the baseline.
    • Areas matching CRITICAL.md keep their build pause.
  3. Safety net. Runs tdd-refactor-guard per area. Where it says NEEDS TESTS, characterization tests are the first task. No net, no refactor.
  4. Plan. Adds one quality-intent "Pay Down Debt" phase:
    • into ROADMAP.md after asking, or as a one-phase roadmap if none exists
    • never renumbering existing phases
    • plan's quality row now describes the debt task shape: test and lint verifies, baseline entries removed
  5. Ratchet.
    • Merges the in-scope fragments into .swiftlint.yml, showing the diff first.
    • Refreshes the baseline, then compares per-rule counts. Growth in a rule that was already baselined is refused and turned into a task, not absorbed.
    • Coverage may only rise.
  6. Track. New templates/DEBT.md with an area table, backlog and a trend row per run. --report stops after writing it.

Also:

  • registered in help (box, Quick Reference, Planning Files), README (54 → 55, plus a table row), CLAUDE.md and MODEL-TIERS (Analysis tier)
  • design-system.md drops its "if installed" fallback
  • CHANGELOG entry

Tested

  • Measurement snippet: extracted verbatim from the command and run on three apps:
    • Specimen: design 1749 · size 78 · practices 29. Views/Projects ranks first (635 violations, 101 commits).
    • Antics: design 185 · size 28 · practices 16. Views and Views/Music rank first.
    • ChantFlow: design 307 · practices 170 · size 29. Shared/Managers ranks first. This run also caught and fixed a bug: folders with spaces had lost their commit counts.
  • ./scripts/validate.sh passes (55 commands).
  • Not run end to end: writing DEBT.md, the phase, or the baseline into a real project. Those steps change the app's repo.

🤖 Generated with Claude Code

rshankras and others added 2 commits November 4, 2026 19:32
…102)

Lints with the project config plus the design-system, code-size,
concurrency and coding-best-practices fragments, ranks areas by
violations x recent commits, freezes untouched areas, and turns the top
areas into a quality-intent phase: characterization tests first, one
area per task, behavior unchanged, baseline only shrinks. Writes
.planning/DEBT.md with a trend row per run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rshankras
rshankras merged commit faf283d into main Nov 4, 2026
2 checks passed
@rshankras
rshankras deleted the feat/102-debt branch November 4, 2026 14:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

New command: /apple:debt — measure an existing app against SwiftShip's best practices and pay the debt down safely

1 participant