# Session 0004.0 — Transcript

> App: engineering
> Start: 2026-06-05T12-37 (PST)
> End: 2026-06-06T00-01 (PST)
> Type: coding
> Status: **FINALIZED**

## Launch prompt

```
Tangent: define best practices for a "Solution Design" (a combined business analyst + product + engineering spec) in the Engineering docs, and reference it in the engineering handbook.

A Solution Design should contain:
- Business Context
- Problem Statement
- Targeted Business Outcome(s) with success metrics
- Business Use Cases — BDD format, business-centric (no product/technical detail), each with acceptance criteria (what does a user successfully completing that business scenario look like?)
- Product Use Cases — BDD format, describe the UX (buttons, notifications, etc.), each linked to a Business Use Case where applicable
- Wireframes — show the user experience; doesn't need to be polished, but UX components should be in approximately the right location
- Technical Design — high-level architecture diagrams, and for each Product Use Case a sequence diagram + technical implementation details
- Delivery Plan — overall approach/strategy, then a Slicing Plan (Slices -> completed Product Use Cases), plus anything else useful for execution

Question to answer: "Am I missing anything?"
```

## Plan

Define a **Solution Design** standard (combined BA + product + engineering spec)
in the engineering docs and reference it from the handbook.

Decisions settled with operator (via AskUserQuestion):
1. **SD *is* the spec** (unify) — Solution Design is the canonical spec format;
   handbook §3's binding-contract content becomes its Technical Design lens,
   Delivery Plan absorbs the roadmap/slicing. Enrich §3 with a new §3.3.
2. **Dedicated guide + template + thin handbook section** — the full standard
   lives in `engineering/solution-design/GUIDE.md` + `TEMPLATE.md`; handbook §3.3
   carries the load-bearing summary + a pointer (per §4.1 doc-leads-automation).
3. **Wireframes: describe canonically, generate on demand** — section 10 is a
   structured *UX Layout description* (the source of truth, git-native, diffable);
   wireframes are generated from it (Claude Design etc.) on demand, not committed.
   Mirrors §3.2 (spec leads) / §4.1 (doc leads automation).

## Pre-state

Clean `main`, in sync with `origin/main`. Engineering registered as an app
(`app.json`). Handbook (`README.md`) structured as numbered §1–§12 with an
existing spec concept: §1 lifecycle (discovery → `SPEC.md` → `ROADMAP` → build),
§2 discovery (prototype or BDD corpus), §3 "Write the first spec", §7 roadmap. No
`solution-design/` dir; no `CLAUDE.md` in the repo.

## Arc

1. **Session gate / init.** Classified the opening prompt as a **coding** session
   (authoring committed docs in the engineering repo) — invoked
   `wgl-session-coding-init`, claimed session **0004** (no other sessions in
   flight). Verified clean pushed `main`. Installed the missing `CLAUDE.md`
   import stub (`@~/.claude/wiggleverse.md`) for future sessions.

2. **Brainstorming.** Explored the repo to ground the design. Key realization:
   the proposed "Solution Design" overlaps the handbook's *existing* lifecycle
   (discovery / `SPEC.md` / `ROADMAP`), so the load-bearing question wasn't
   "which sections" but "how does it relate to the existing spec concept."

3. **Answered "Am I missing anything?"** with a grouped gap analysis, flagging
   the Wiggleverse-specific additions tied to existing handbook rules: front
   matter/status & versioning (§3.1#5), stakeholders/personas, explicit
   scope/non-goals (§3.1#4), assumptions/constraints/deps, guardrail metrics,
   negative/edge BDD scenarios, a traceability matrix, **invariants** (§3.1#1),
   data model & interface contracts (§3.1#2), NFRs incl. the hard secrets rule
   (§6.3), key decisions/alternatives, testing strategy (§10.3), rollout/canary
   (§10), risks, and an open-questions/decisions log.

4. **Settled two structural forks via AskUserQuestion** — both → recommended:
   SD *is* the spec (unify); dedicated guide + template + thin handbook section.

5. **Operator pushback on wireframes.** Asked whether ASCII-in-markdown
   wireframes would actually succeed, or whether to describe UX and generate
   wireframes (e.g. Claude Design). Agreed the description should be canonical
   (git-native, diffable, the contract) and wireframes a generated rendering —
   consistent with §3.2/§4.1. Third AskUserQuestion settled it →
   **describe canonically, generate on demand, don't commit images.**

6. **Authored the deliverables** on `docs/solution-design-standard`:
   `solution-design/GUIDE.md` (full standard), `solution-design/TEMPLATE.md`
   (copy-to-start skeleton with worked BDD / Mermaid / UX Layout / table stubs),
   `README.md` §3.3 + TOC, and the `CLAUDE.md` stub. Verified fences/anchors.

7. **Landed it.** Committed, pushed. `gh pr create` was denied (gh targets
   GitHub, not the Gitea host); created the PR via the Gitea API helper
   (`gitea-api.sh`, Keychain token) → PR **#12**, mergeable. Merged (autonomous
   posture), synced local `main`, deleted the branch.

## Cut state

- PR **#12** merged to `main` (`51b99d1`). `main` clean and synced.
- New: `solution-design/GUIDE.md`, `solution-design/TEMPLATE.md`, `CLAUDE.md`.
- Edited: `README.md` (§3.3 + TOC).
- Stale local branches from prior sessions left untouched (`dev-env/v0.1`,
  `docs/retire-operator-cli-repo-role`, `session-0046/*`).

## Operator plate / follow-ups

- **Optional:** add a one-line Solution Design pointer to the auto-loaded digest
  (`agent-context.md`), since a spec/discovery session won't otherwise learn the
  format automatically. Logged in memory as a possible follow-up.

## Deferred decisions

_No low-confidence autonomous calls this session — the three structural
decisions (SD-is-spec, guide+template placement, wireframe approach) were all
made *with* the operator via AskUserQuestion, not deferred._