---
title: "Fix Learnings from Full Run - Doctor and Local Cache"
type: fix
status: active
date: 2026-03-25
origin: auto-generated by MakeBestCLI full run 2026-03-25T07:49:59
---

# Fix Learnings from Full Run

## Source Data

Full press run on 3 APIs (2026-03-25):

| API | Level | Gates | Steinberger | Grade |
|-----|-------|-------|-------------|-------|
| petstore | EASY | 7/7 | 53/80 (66%) | B |
| plaid | MEDIUM | 7/7 | 55/80 (68%) | B |
| notion | HARD | 7/7 | 53/80 (66%) | B |

## Consistent Gaps (same problem across all 3)

- **doctor: 2/10** on all 3 APIs
- **local_cache: 0/10** on all 3 APIs

Fixing these pushes 66-68% to ~78-80% (Grade B -> Grade A territory).

## Implementation Units

### Unit 1: Improve Doctor Template (2/10 -> 6+/10)

**File:** `internal/generator/templates/doctor.go.tmpl`

**What's wrong:** Doctor creates one HTTP client and does a basic connectivity check. The scorecard detects `http.Client` once = 2 points. We need more health check patterns.

**What to add to doctor.go.tmpl:**

1. **Config check** - verify config file loads without error
2. **Auth check** - verify auth env vars are set (loop over Auth.EnvVars)
3. **Connectivity check** - HEAD request to BaseURL (already exists but needs more patterns)
4. **Version check** - try GET /version or /health or /status endpoints
5. **Each check prints OK/WARN/FAIL** with color

The template should generate 3+ `http.NewRequest` or `http.Get` calls so the scorecard detects them.

**Verification:** Generate petstore CLI, run scorecard, doctor dimension >= 6/10.

### Unit 2: Add HTTP Response Cache to Client Template (0/10 -> 3+/10)

**File:** `internal/generator/templates/client.go.tmpl`

**What's wrong:** No caching. Every GET hits the network.

**Minimal fix (not SQLite - just file cache):**

Add to client.go.tmpl:
- A `cacheDir` field (defaults to `~/.cache/<cli-name>/`)
- On GET requests: hash URL+params, check if cache file exists and is < 5 min old
- If cached: return cached response
- If not: fetch, write to cache, return
- Add `--no-cache` flag to root.go.tmpl to bypass

**The scorecard needs to detect this:** Update `scoreLocalCache` in scorecard.go to also look for "cacheDir" or "cache" patterns in `internal/client/client.go`.

**Verification:** Generate petstore CLI, run scorecard, local_cache dimension >= 3/10.

### Unit 3: Re-run Full Press and Verify Score Improvement

```bash
FULL_RUN=1 go test ./internal/pipeline/ -run TestFullRun -v -timeout 10m
```

**Expected results after fixes:**

| Dimension | Before | After |
|-----------|--------|-------|
| Doctor | 2/10 | 6+/10 |
| Local Cache | 0/10 | 3+/10 |
| Steinberger Total | 53-55/80 | 60-64/80 |
| Percentage | 66-68% | 75-80% |
| Grade | B | B+ or A |

## Scope Boundaries

- Do NOT add SQLite FTS5 caching (that's a separate plan)
- Do NOT change other templates - only doctor.go.tmpl and client.go.tmpl
- Do NOT add new scorecard dimensions
- The file cache is intentionally simple (5 min TTL, file-based, no invalidation)
