# ADR-099 DevGuide Is an Index + Skill + Topic Files, Not a Monolith

## Status

Accepted, 2026-07-02.

## Status History

```yaml
status_history:
  - date: 2026-07-02
    status: Proposed
    changed_by: hkl
    reason: pwa_dev_style.md at 1,772 lines (~50k tokens) consumed a quarter of a session context window whenever loaded
    changed_via: adr-kit (360lm)
  - date: 2026-07-02
    status: Accepted
    changed_by: hkl
    reason: Restructure executed and verified (VCC improvement plan Phase 3); line-accounting confirmed verbatim move
    changed_via: adr-kit (360lm)
```

## Context

`pwa_dev_style.md` grew into a 1,772-line monolith (~50k tokens) covering the pre-build
questionnaire plus 24 implementation sections. Any session that consulted it — even for one
topic like the photo pipeline — paid the full context cost, crowding out room for actual work.
LLM guidance for current models (Claude Fable 5 migration notes) also recommends less
prescriptive, on-demand loading of skills/references. The VCC improvement plan (Phase 3,
2026-07-02) mandated a context-efficient restructure. Affects: every future PWA build and
every session touching PWA patterns.

## Decision

- `pwa_dev_style.md` stays at its path but is an **index only** (~40 lines). Never re-inline content.
- The 24 content sections moved **verbatim** (sed line-range split, line-count verified) to 14
  topic files under `docs/style/` (identity-and-design-system, state-and-storage,
  screens-and-modals, photo-pipeline, stores-and-gps, sync-and-backend, admin-draft-view-init,
  service-worker-and-utils, reports-and-slides-gas, activity-response-patterns,
  bilingual-pattern, app-update-banner, client-portal-session-bridge, admin-pwa-extensions).
- The Q0.1–Q0.14 pre-build questionnaire moved to the **`/new-pwa` skill**
  (`~/.claude/skills/new-pwa/SKILL.md`), which is the mandatory entry point for scaffolding any
  new PWA and maps questionnaire answers → which topic files to load.
- Sessions load **only** the topic files the task needs.
- The pre-split original is archived at `/root/vcc-backups/phase3-pre-2026-07-02/pwa_dev_style.md`.

## Alternatives Considered

1. **Keep the monolith, rely on partial reads (offset/limit).** Rejected: section boundaries are
   invisible to a fresh session; partial reads routinely miss cross-references, and the habit of
   "read the whole guide" persisted in practice.
2. **Move everything into CLAUDE.md/memory.** Rejected: CLAUDE.md is auto-loaded into every
   session — would make the per-session fixed cost worse, not better.
3. **Delete the old path and use only docs/style/.** Rejected: dozens of references (memory
   files, aliases, ADRs, muscle memory) point at `pwa_dev_style.md`; keeping it as an index
   preserves every inbound link.

## Consequences

- New-PWA flow drops from ~50k tokens to ~4k (skill) + only-needed topics (~2–6k each).
- The `/new-pwa` skill becomes the enforcement point for Q0 (including ⚑ Indian amount
  formatting and ⚑ proof-image confirmations) and ADR cross-checks.
- Topic files must carry the "part of the split" header; edits go to the topic file, and new
  topics get a new file + one index row — not appended to the index body.
- Risk: content drift across 14 files instead of 1 — mitigated by the index table and the
  weekly memory-freshness cron (Phase 2).