docs: add technical debt audit

[jackgranatowski]

Full 9-dimension audit of core/, optional/, configurator/, scripts/,
tests/, and docs/. 34 findings (0 Critical, 1 High, 15 Medium, 18 Low),
verified against clean tsc/svelte-check/stylelint/madge/npm-audit
baselines. Highest-impact items: zero test coverage on the configurator's
interactive layer, deliberately obfuscated codec.ts naming, and
duplicated parsing helpers across the doc-gen scripts.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_013cK9t8cQQn4DNweTjJzVZi

[coderabbitai]

Warning

Review limit reached

@jackgranatowski, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 17 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9abfa385-6f4d-4742-9e4d-ead1ecd269e1

📥 Commits

Reviewing files that changed from the base of the PR and between bad96c1 and b97fd8d.

📒 Files selected for processing (2)

• docs/technical-debt-audit.md
• docs/technical-debt-remediation-plan.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/codebase-audit-protocol-qr7xrn

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Docs: add technical debt audit and sequenced remediation plan

📝 Documentation 🕐 20-40 Minutes

AI Description

• Add a repo-wide technical debt audit with prioritized findings and verification baselines.
• Add a sequenced, multi-PR remediation plan covering SLASHED and SLASHED-Plugins.
• Document recommended PR ordering, verification steps, and maintainer questions.

Diagram

graph TD
  A["SLASHED repo"] --> B[/"technical-debt-audit.md"/] --> C["Findings (SL-001..034)"] --> D[/"remediation-plan.md"/] --> E(["Planned SLASHED PR waves"]) --> F(["Planned Plugins PR waves"])
  F --> G["Sync vendored configurator"]

  subgraph Legend
    direction LR
    _repo["Repo"] ~~~ _doc[/"Doc"/] ~~~ _plan(["Planned PR wave"])
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Track findings as GitHub Issues/Projects (docs link to issues)

• ➕ Better assignment/ownership, status tracking, and notifications
• ➕ Easier to query/report progress over time
• ➖ More overhead to create and maintain 70+ issues
• ➖ Harder to keep a single narrative/mental model in one place

2. Encode remediation plan as ADRs or RFCs per theme

• ➕ Clear decision history and scope boundaries per change wave
• ➕ Encourages explicit tradeoffs and accepted constraints
• ➖ Heavier process than needed for many low-risk hygiene items
• ➖ Splits context across multiple documents instead of one plan

Recommendation: Current approach (audit + sequenced remediation plan docs) is the best default: it centralizes context, prioritization, and verification in a reviewable artifact without imposing workflow overhead. If execution stalls or ownership becomes unclear, consider promoting Medium/High findings into Issues while keeping these docs as the authoritative index and rationale.

Files changed (2) +357 / -0

Documentation (2) +357 / -0

technical-debt-audit.mdAdd repo-wide technical debt audit with findings and priorities +109/-0

Add repo-wide technical debt audit with findings and priorities

• Introduces a detailed audit with tooling baselines, an architectural mental model, and 34 categorized findings with severity/effort and recommendations. Includes a prioritized Top 5 list, quick wins checklist, and maintainer questions to unblock ambiguous items.

docs/technical-debt-audit.md

technical-debt-remediation-plan.mdAdd multi-PR remediation plan and sequencing across repos +248/-0

Add multi-PR remediation plan and sequencing across repos

• Adds a sequenced remediation plan mapping findings into themed PR waves for SLASHED and SLASHED-Plugins, including explicit dependency ordering and verification steps. Captures key design-review corrections (e.g., maskComments vs stripComments semantics) and calls out deferred items requiring maintainer input.

docs/technical-debt-remediation-plan.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 6 rules

1. Non-portable plan commands 🐞 Bug ⚙ Maintainability

Description

docs/technical-debt-remediation-plan.md hardcodes local absolute paths (e.g. /home/user/SLASHED)
and instructs copying to "$TMPDIR/audit-verify-before/" without ensuring that directory exists, so
the verification steps can fail when followed verbatim. This reduces the plan’s usefulness as a
repeatable procedure for other contributors and CI environments.

Code

docs/technical-debt-remediation-plan.md[R80-81]

+cd /home/user/SLASHED
+npm run docs && cp docs/api-index.json token-registry.json "$TMPDIR/audit-verify-before/"

Relevance

⭐⭐⭐ High

Team often accepts doc instruction/accuracy fixes; similar docs corrections accepted in PRs #142 and
#415.

PR-#142
PR-#415
PR-#266

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The remediation plan includes hardcoded absolute paths and a cp target directory under $TMPDIR that
is never created, making the steps non-portable and potentially non-runnable as written.

docs/technical-debt-remediation-plan.md[9-12]
docs/technical-debt-remediation-plan.md[78-86]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The remediation plan contains copy/paste commands that are environment-specific and can fail:
- Uses hardcoded absolute paths like `/home/user/SLASHED`.
- Copies into `"$TMPDIR/audit-verify-before/"` without creating the directory.

### Issue Context
These commands are meant to be executed by other contributors and in different environments; they should work regardless of checkout location.

### Fix Focus Areas
- docs/technical-debt-remediation-plan.md[9-12]
- docs/technical-debt-remediation-plan.md[78-86]

### Suggested change
- Replace `cd /home/user/SLASHED` with a portable alternative, e.g.:
 - `cd "$(git rev-parse --show-toplevel)"`
 - or instruct setting `SLASHED_ROOT` and using `cd "$SLASHED_ROOT"`
- Replace the `cp ... "$TMPDIR/audit-verify-before/"` pattern with a created temp dir, e.g.:
 - `audit_dir="$(mktemp -d)"`
 - `cp ... "$audit_dir/"`
 - (or `mkdir -p "$TMPDIR/audit-verify-before"` before copying).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Non-portable plan commands 🐞 Bug ⚙ Maintainability

docs/technical-debt-remediation-plan.md hardcodes local absolute paths (e.g. /home/user/SLASHED)
and instructs copying to "$TMPDIR/audit-verify-before/" without ensuring that directory exists, so
the verification steps can fail when followed verbatim. This reduces the plan’s usefulness as a
repeatable procedure for other contributors and CI environments.

Agent Prompt

### Issue description
The remediation plan contains copy/paste commands that are environment-specific and can fail:
- Uses hardcoded absolute paths like `/home/user/SLASHED`.
- Copies into `"$TMPDIR/audit-verify-before/"` without creating the directory.

### Issue Context
These commands are meant to be executed by other contributors and in different environments; they should work regardless of checkout location.

### Fix Focus Areas
- docs/technical-debt-remediation-plan.md[9-12]
- docs/technical-debt-remediation-plan.md[78-86]

### Suggested change
- Replace `cd /home/user/SLASHED` with a portable alternative, e.g.:
  - `cd "$(git rev-parse --show-toplevel)"`
  - or instruct setting `SLASHED_ROOT` and using `cd "$SLASHED_ROOT"`
- Replace the `cp ... "$TMPDIR/audit-verify-before/"` pattern with a created temp dir, e.g.:
  - `audit_dir="$(mktemp -d)"`
  - `cp ... "$audit_dir/"`
  - (or `mkdir -p "$TMPDIR/audit-verify-before"` before copying).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools