Skip to main content

Decision — Admin-IA acceptance spec lives as one cross-cutting doc, not updates to 9 per-tier specs

Problem​

knowledge/acceptance/ holds 9 per-plan Layer-3 specs (starter-chat.md, pro-both.md, cwa-pro-website.md, etc.). CLAUDE.md rule 17 forbids building customer-facing tier-gated UI without an acceptance spec.

The P1 admin-IA redesign (collapse 9 tabs → 4 universal tabs, gated per plan + capability) cross-cuts every tier. Updating each of the 9 per-plan specs to mirror the new IA is ~6-8 hours of doc work AND creates drift risk — 9 specs containing the same IA rules can fall out of sync.

Decision​

Create ONE cross-cutting spec at knowledge/acceptance/admin-ia-2026-04-18.md that defines expected outputs for the admin dashboard across all plans × roles. Per-plan specs reference it for admin-dashboard sections but are NOT duplicated.

The canonical source of truth for cap + plan gating remains knowledge/architecture/admin-nav-capability-map.md. The acceptance spec renders the matrix as expected outputs the customer sees.

Rationale​

  1. Single source of truth — one spec to update, one to test against. Drift risk eliminated.
  2. Matches the code shape — the admin shell IS one React component tree gated at runtime; the spec should match.
  3. Compatible with rule 17 — a spec exists before Slice 2+ code ships; just not in 9 different files.
  4. Reversible — if per-tier drill-down is wanted later, the cross-cutting spec can be split per-plan without breaking references.

Trade-off accepted​

Per-plan specs (starter-chat.md, pro-both.md, etc.) no longer hold admin-dashboard expected-output sections. Readers looking up "what does a Starter Chat admin see in Inbox?" must follow a one-hop link from the per-plan spec to the cross-cutting admin-IA spec. Trade-off: a hop vs duplication.

Retroactive coverage for Slice 1​

Slice 1 (PR #65, Settings → slide-over) merged before this decision. The cross-cutting spec (written 2026-04-18) retroactively covers Slice 1 so it's compliant as of merge+1 commit.

Implementation​

  • New file: knowledge/acceptance/admin-ia-2026-04-18.md (Layer 3 spec)
  • Per-plan specs updated with a one-paragraph "Admin dashboard — see admin-ia-2026-04-18.md" reference at their admin-dashboard sections (low-effort update, batchable)
  • Cap-map + design spec + sprint plan all link to the new acceptance spec

Revisit if​

  • A single plan's admin dashboard diverges significantly from universal IA (hasn't happened in 2 years; unlikely).
  • Per-tier drill-down is wanted by a specific customer-facing team.