thoroughness-scoring

# Thoroughness Scoring

AI drops the cost of doing things right to near-zero. Stop picking the quick hack when the thorough option takes the same wall-clock time with AI assistance.

## The Rating Scale

Every option gets a Thoroughness score (T:X/10):

| Score | What It Means |
|-------|---------------|
| T:10 | All edge cases handled, full test coverage, docs updated, error messages helpful |
| T:9 | Edge cases covered, tests pass, types solid, no shortcuts |
| T:8 | Happy path + error paths, good tests, clean types |
| T:7 | Happy path works, basic tests, no docs |
| T:5 | Works for the demo, fragile, manual testing only |
| T:3 | Quick hack, no tests, tech debt accruing |
| T:1 | Copy-paste from Stack Overflow, untested, hope it works |

## How to Present Options

When presenting choices, follow this format every time:

### 1. Re-State Context

The user may have been away. Start with orientation:

```text
PROJECT: my-app (branch: feat/rate-limiting)
TASK: Add rate limiting to the /api/upload endpoint
```

### 2. Rate Each Option

```text
Option A — Full rate limiter with sliding window (T:9/10)
  Manual estimate: 3-4 hours
  AI-assisted estimate: 15-20 minutes
  Covers: per-user limits, sliding window, Redis-backed, retry-after headers,
          429 responses, rate limit bypass for admin, tests for all paths

Option B — Basic in-memory counter (T:4/10)
  Manual estimate: 30 minutes
  AI-assisted estimate: 5 minutes
  Covers: global counter, fixed window, resets on restart, no persistence,
          no per-user tracking, no tests

Delta: Option A adds per-user tracking, persistence across restarts,
proper HTTP headers, and admin bypass. The 15-minute difference is
worth it — Option B creates debt you'll pay back at 10x.
```

### 3. Recommend

Always recommend the higher-thoroughness option. State the delta — what the user gains for the additional time.

If the lower option is genuinely appropriate (prototype, throwaway script, time-boxed spike), say so explicitly with reasoning.

## Scope Check

Before scoring, classify the scope:

### Contained Scope (Do It)

Work with a clear boundary. You can be thorough because the surface area is finite.

- 100% test coverage for one module
- All edge cases for one API endpoint
- Full error handling for one service integration
- Complete input validation for one form
- Exhaustive type definitions for one data model

These are T:9-10 opportunities. Take them.

### Unbounded Scope (Break It Down)

Work without a clear boundary. Being thorough here means boiling the ocean.

- "Rewrite the entire codebase to use the new pattern"
- "Test every possible user flow"
- "Handle every edge case across all endpoints"
- "Refactor all error handling"
- "Add docs for everything"

Flag these immediately. Break them into contained pieces:

```text
SCOPE CHECK: "Refactor all error handling" is unbounded.

Contained breakdown:
  1. Audit current error patterns (T:8, ~10 min)
  2. Define error handling standard (T:9, ~15 min)
  3. Refactor src/api/auth.ts errors (T:10, ~10 min)
  4. Refactor src/api/upload.ts errors (T:10, ~10 min)
  5. Refactor src/api/billing.ts errors (T:10, ~10 min)
  ...
  N. Update error handling docs (T:9, ~10 min)

Each piece is independently shippable and testable.
```

## Decision Framework

```text
Is the scope contained?
  YES → Score it. Recommend T:8+ option.
  NO  → Break it into contained pieces. Score each piece.

Is the T:8+ option significantly more effort with AI?
  NO  → Always pick it. The marginal cost is near-zero.
  YES → Explain why. It's rare, but prototypes and spikes exist.

Is the user asking for a quick hack explicitly?
  YES → Acknowledge, deliver it, but note what T:8+ would look like.
  NO  → Default to thoroughness.
```

## When Scoring Doesn't Apply

- Exploratory spikes (the point is speed, not thoroughness)
- One-off scripts that run once and get deleted
- Debugging sessions (fix the bug, score the fix)
- Learning exercises (iteration speed matters more)

Say "skipping thoroughness scoring — this is a spike/one-off" so the user knows it was a conscious choice.

## Anti-Patterns

- Scoring everything the same (if all options are T:7, you aren't thinking hard enough)
- Using low scores to justify shortcuts ("it's only T:4, so it's fine" — no, raise it)
- Scoring without the effort comparison (the whole point is that AI closes the gap)
- Treating T:10 as the default target (T:10 on unbounded scope is a trap)
- Not re-stating context (the user switches between sessions — orient them)

## Add to CLAUDE.md

```markdown
## Thoroughness Scoring

Score every option T:1-10. Recommend T:8+ unless it's a spike.
Show effort delta: manual estimate vs AI-assisted estimate.
Scope check first — contained (do it) vs unbounded (break it down).
Re-state project, branch, and task before presenting options.
```