design-debt

Design Debt

Surface drift — the gap between how the codebase was meant to be structured and how it actually is.

Philosophy

"Is our system getting harder to reason about because of drift?"

Design debt is quiet. No test fails, no lint warns. But new contributors ask more questions, changes take longer, bugs appear in "how do these modules talk to each other." Design-debt finds the drift before it compounds.

Not a refactoring plan. The value is spotting inconsistency, not prescribing a fix. The team decides whether to realign or to formalize the new pattern.

Scope

User may specify a directory. Default: ask which part of the codebase to focus on. This skill works best on a bounded slice (a module, a layer), not whole-codebase scans.

Config Integration

Follow references/config-migration.md for preflight.

Read .assistant-config.md for:

• Architecture Principles (optional — ground truth if declared)
• Stack
• Acknowledged Debt

If no architecture principles are declared, infer the dominant pattern from the code and flag deviations.

Stack Detection

Language/framework context matters (Express vs. Next.js handlers have different norms). Detect via manifest as in other dimensions.

Process

1. Understand context

Read a representative handful of files in the scope. Identify:

• The dominant structural pattern (e.g. "handlers are thin, delegate to services")
• The dominant error-handling style (e.g. "try/catch, JSON envelope")
• The dominant naming convention

2. Scan

• Error handling inconsistency: read all handlers (or equivalent). Compare error shapes.
• Response shape inconsistency: same, for success responses.
• Naming inconsistency: Glob filenames, Grep function names.
• Architectural drift: Grep for imports that cross declared boundaries (e.g. services importing handlers, handlers doing direct DB calls).
• Duplicated logic: Grep for similar function signatures across files.

3. Group by concern