Technical Debt Impact Analyzer with Auto-Issue Generation for High-Priority Refactors

[github-actions]

Strategic Improvement

Platform health scan identifies 48 hardcoded values, 67 fallbacks, 51 TODOs, 20 HACKs, but lacks prioritization and automated action. Build impact analyzer that scores each debt item by: change frequency of affected file, blast radius, test coverage, and strategic importance. Auto-generate GitHub issues for top-10 highest-impact refactors, enabling the platform to systematically improve itself.

Acceptance Criteria

• Parse platform hygiene scan output (159 file:line entries) into structured debt items
• Score each item (0-100) using: git log file change frequency, script size, test coverage, hardcoded vs TODO vs HACK severity
• Generate detailed issue for top-10 items with title, description, acceptance criteria, and strategic rationale
• Create issues via gh CLI with label "platform-self-improvement" and priority tag
• Emit summary report showing debt reduction roadmap over next 4 weeks
• Schedule weekly runs via CI to continuously identify new high-priority debt

Context

• Priority: P6
• Complexity: fast
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P6: Platform Self-Improvement (AGI-Level Readiness)

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Aligns with Shipwright's platform self-improvement strategy; requires scoring engine, issue generator, and CI scheduling across 3-4 files.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	25214390529

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (197 lines)

Implementation Plan: Technical Debt Impact Analyzer with Auto-Issue Generation

Goal

Build a debt impact analyzer that consumes existing shipwright hygiene platform-refactor scan output (.claude/platform-hygiene.json), scores each debt item (0–100) using git change frequency, blast radius, script size, test coverage proxy, and severity, then auto-generates GitHub issues for the top-10 highest-impact refactors. Schedule weekly runs via CI.

---

Brainstorming / Socratic Refinement

Requirements clarity

• Minimum viable change: a single new script scripts/sw-debt-analyzer.sh reading .claude/platform-hygiene.json, ranking findings, writing a 4-week roadmap, and (when not in dry-run and $NO_GITHUB != true) creating GitHub issues. CLI router entry + test suite + weekly workflow.
• Implicit requirements: idempotency (no duplicate issues across runs), NO_GITHUB guard, atomic file writes, bash 3.2 compat, label platform-self-improvement auto-created if missing, priority tag derived from score band, observability via emit_event.
• Acceptance criteria (from issue): parse 159 entries → structured items; score 0–100; top-10 issues generated; gh CLI w/ label + priority; 4-week roadmap report; weekly CI.

Design alternatives

1. New standalone script + CLI subcommand (chosen). Lives at scripts/sw-debt-analyzer.sh, registered in scripts/sw router, dedicated test suite, weekly GH Actions workflow. Reuses existing platform-hygiene.json. Pros: clear separation, easy to test, mirrors existing module pattern (~30 sibling scripts at this size). Cons: one more file.
2. Extend sw-hygiene.sh with a score subcommand. Pros: fewer files. Cons: sw-hygiene.sh is already 660 lines and serves detection, not prioritization/action. Mixing scan + ranking + issue creation violates single-responsibility and bloats both concerns.
3. Embed in sw-intelligence.sh. Pros: rides intelligence cache. Cons: intelligence layer is analysis only — coupling it to GitHub side-effects inverts the dependency direction.

Choice: Option 1. Smallest blast radius, follows existing naming/module conventions, easiest rollback (delete one script + workflow + test).

Risk & dependency analysis

• Depends on .claude/platform-hygiene.json — analyzer must validate input or invoke shipwright hygiene platform-refactor to refresh.
• Depends on gh CLI; auth must exist in CI. Guard with [[ "${NO_GITHUB:-false}" != "true" ]].
• Risk: weekly cron creating duplicates → addressed via dual dedup (gh search + local ledger).
• No reverse dependencies — purely additive.

Simplicity check

Reuse: hygiene scan output, lib/compat.sh, lib/helpers.sh, gh, jq. No new libraries. Target ~350 LoC.

---

Files to Modify / Create

Create

• scripts/sw-debt-analyzer.sh — main analyzer (parse → enrich → score → roadmap → issues)
• scripts/sw-debt-analyzer-test.sh — test suite (mock gh, fixture JSON, 12+ cases)
• .github/workflows/shipwright-debt-analyzer.yml — weekly cron + manual dispatch
• config/debt-weights.json — tunable scoring weights with defaults

Modify

• scripts/sw — add debt-analyzer (alias debt) subcommand dispatch
• package.json — register test:debt-analyzer in test scripts and combined test runner
• .claude/CLAUDE.md — AUTO:core-scripts and AUTO:test-suites get the new rows on next shipwright docs sync (no manual edit required)

Created at runtime (not committed)

• .claude/pipeline-artifacts/debt-roadmap.md and debt-roadmap.json
• .claude/debt-state.json — local ledger of created issues for idempotency

---

✅ Task Checklist

• Task 1: Create scripts/sw-debt-analyzer.sh skeleton with VERSION, sourcing, help, subcommand dispatch.
• Task 2: Implement parse_findings() reading platform-hygiene.json and resolving severity per line.
• Task 3: Implement batched git-frequency table + per-file enrichers (script_size, test_coverage_proxy, blast_radius).
• Task 4: Implement score_items() jq pipeline with config-driven weights and p95 normalization.
• Task 5: Implement roadmap subcommand emitting markdown + JSON via atomic writes.
• Task 6: Implement auto-issue flow with DEBT-SIG dedup (ledger + gh search), label/priority creation, NO_GITHUB/--dry-run guards.
• Task 7: Register debt-analyzer/debt in scripts/sw router.
• Task 8: Create config/debt-weights.json with documented defaults.
• Task 9: Write scripts/sw-debt-analyzer-test.sh with 12+ test cases (mock gh, fixture JSON).
• Task 10: Add test:debt-analyzer to package.json scripts and combined test runner.
• Task 11: Create .github/workflows/shipwright-debt-analyzer.yml (weekly cron + manual + concurrency guard).
• Task 12: Add emit_event "debt_analyzer_run" instrumentation.
• Task 13: Run npm test — verify no regressions in any existing suite.
• shipwright debt-analyzer and alias shipwright debt invokable via scripts/sw.
• Parses 159+ findings from .claude/platform-hygiene.json into structured records with severity.
• Each item scored 0–100 reproducibly (golden test fixture pins ordering).
• Top-10 issues generated with title, body, acceptance criteria, strategic rationale, platform-self-improvement label, priority/P{0..3} tag.
• Idempotent: second run creates 0 duplicates (dedup verified via DEBT-SIG ledger + gh search).
• 4-week roadmap markdown + JSON written atomically.
• Weekly GH Actions workflow on main with permissions: issues: write and concurrency guard.

---

Generated by shipwright pipeline at 2026-05-01T12:43:25Z

[github-actions]

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (175 lines)

Design: Technical Debt Impact Analyzer with Auto-Issue Generation for High-Priority Refactors

Context

The repository accumulates technical debt markers (TODO/FIXME/HACK/KLUDGE/hardcoded values/Fallback patterns) detected by shipwright hygiene platform-refactor (writes .claude/platform-hygiene.json, currently 159 entries). Detection exists; prioritization and action do not. Engineers cannot tell which debt items have the highest impact, and nothing converts them into trackable work.

Constraints from the codebase:

• Bash 3.2 compatibility (no declare -A, no readarray, no ${var,,}) — per .claude/CLAUDE.md development guidelines.
• Module pattern: ~30 sibling scripts/sw-*.sh files in the 300–700 LoC range, each with paired *-test.sh.
• CLI router: scripts/sw dispatches subcommands via exec.
• GitHub guard: NO_GITHUB and --dry-run must short-circuit side effects.
• Atomic writes (tmp + mv), set -euo pipefail, emit_event instrumentation.
• Test harness: temp REPO_DIR, mock binaries on PATH, PASS/FAIL counters, ERR traps.
• Project metadata reports language: typescript / vitest, but the actual implementation surface is bash — Node tooling is unrelated to this feature.

Decision

Add a single-purpose bash module scripts/sw-debt-analyzer.sh that reads hygiene scan output, scores items, emits a roadmap, and creates GitHub issues with strict idempotency. Five components with one-way dependencies.

Component Diagram

                 ┌─────────────────────────────────────────────┐
                 │  CLI Router (scripts/sw)                    │
                 │  exec sw-debt-analyzer.sh "$@"              │
                 └────────────────────┬────────────────────────┘
                                      │
                 ┌────────────────────▼────────────────────────┐
                 │  Orchestrator (sw-debt-analyzer.sh main)    │
                 │  parse → enrich → score → roadmap → issue   │
                 └──┬──────────┬─────────┬─────────┬───────────┘
                    │          │         │         │
        ┌───────────▼──┐  ┌────▼─────┐ ┌─▼──────┐ ┌▼──────────────┐
        │ Parser       │  │ Enricher │ │ Scorer │ │ IssueWriter   │
        │ (jq + sed)   │  │ (git/fs) │ │ (jq)   │ │ (gh + ledger) │
        └──────┬───────┘  └────┬─────┘ └───┬────┘ └──────┬────────┘
               │               │           │             │
               ▼               ▼           ▼             ▼
       platform-hygiene  git-freq.tbl  weights.json  debt-state.json
           .json         (tmp)         (config)      (ledger)

Dependencies point inward: Orchestrator depends on the four pure functions; none of them call back. IssueWriter is the only component with side effects on remote state.

Data Flow

1. sw debt-analyzer auto-issue → router execs script.
2. Parser loads .claude/platform-hygiene.json, validates non-empty findings_sample, re-greps each {file,line} to assign severity (1–4) → emits items[] JSON to stdout.
3. Enricher computes one upfront git frequency table (git log --since=90.days --name-only → awk counts → tmp file), then per-item adds change_freq, script_size, test_coverage_proxy, blast_radius → emits enriched items[].
4. Scorer reads weights from config/debt-weights.json, applies normalized weighted formula in a single jq pipeline using p95 normalization → emits sorted-desc items[] with score field.
5. Orchestrator slices top-10 → 4 tranches (3,3,2,2), atomic-writes debt-roadmap.{md,json} to .claude/pipeline-artifacts/.
6. IssueWriter for each top-10: compute DEBT_SIG = sha1(file:line:severity), check local ledger, then gh issue list --search "DEBT-SIG: $sig in:body"; if both miss, ensure label exists, create issue, atomic-append ledger.

Interface Contracts

// Parser
parse_findings(hygiene_path: string): JSON<{
  items: Array<{file: string, line: int, severity: 1|2|3|4, marker: string}>
}>

</details>

---
_Generated by `shipwright pipeline` design stage at 2026-05-01T12:46:10Z_

[github-actions]

[github-actions]

🔨 Build started — shipwright loop with 20 max iterations, 1 agent(s), model: opus

[github-actions]

❌ Pipeline failed at stage build after 6m 16s.

No log available

[github-actions]