113 lines
5.9 KiB
Markdown
113 lines
5.9 KiB
Markdown
# 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._
|