# Workflow Brainstorm > Workflow — Brainstorm - Skill: `persimmon-automation-labs/workflow-brainstorm` (Agent Skill) - Install (CLI): `npx skillmds@latest add persimmon-automation-labs/workflow-brainstorm` - Raw SKILL.md: https://api.skillmd.com/api/skills/persimmon-automation-labs/workflow-brainstorm/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: Persimmon-Automation-Labs (https://skillmd.com/u/persimmon-automation-labs) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/persimmon-automation-labs/workflow-brainstorm --- # Workflow — Brainstorm Step 1 of the Persimmon workflow. Turn a rough request into an approved spec **before** any code. Adapted from obra/superpowers `brainstorming`. ## Trigger - Any non-trivial new feature, page, integration, or schema change - Routed here by the `workflow` mother / `persimmon` gate ## Process 1. **Ask one question at a time.** Refine the rough idea through a dialogue — do not dump a list of 10 questions. Cover: who operates this, what problem it solves, what success looks like, what's explicitly out of scope, and what data/integrations it touches. 2. **Surface alternatives.** Present 2–3 viable approaches with trade-offs (effort, risk, fit to the Persimmon stack). Recommend one. 3. **Present the design in sections** short enough to read. Get explicit sign-off per section before moving on. 4. **Write the spec** to the CLIENT repo at `docs/specs/YYYY-MM-DD-{topic}.md` using the template below. 5. **Block approval** if the `## Business meaning` section is missing or empty. ## Spec template ```markdown # {Title} ## Business meaning What this change means for the client's operators (not the code). Who does what differently, and why it matters to the firm. (REQUIRED — approval blocks without it.) ## Problem The concrete problem, in the operator's words. ## Goals / Non-goals - Goal: … - Non-goal: … (what we are deliberately NOT doing) ## Approach Chosen approach + why, with the alternatives considered and rejected. ## Stack impact New routes / Server Actions / Prisma models / migrations / prompts / env vars / deps. Flag anything that needs `force-dynamic`, a new bucket/CORS origin, or a new secret. ## Risks & open questions Anything still unknown or client-blocked. ## Acceptance (high level) Bullet outcomes a human can verify. (Detailed EARS criteria come in `workflow-plan`.) ## Skills applied ← REQUIRED at T1/T2 (workflow-traceability) The provenance footer: which skills were READ for which decisions (e.g. "IA → frontend-public-site-conventions; data model → data-schema-design; auth → security-nextauth"), and a `Decisions needing research:` line listing what was researched. An empty footer on a non-trivial spec is a defect — it means the design can't be traced to applied skills. `workflow-spec-review` verifies this. ``` ## Traceability (tiered — see `workflow-traceability`) Per the tiering matrix (`project-type` × `project-stage`): - **At T1/T2** (operated surfaces / past prototype), give every acceptance criterion a stable **`REQ---`** ID and a cited **source** (`SOW §x` | `ADR-` | `constitution:`), kept in `docs/requirements/requirements.md`; name each screen by its **mockup filename** (`SCREEN-`) and capture the actors as a **persona registry** (`docs/requirements/personas.md`). IDs are what let `traceability-audit` and `workflow-flow-review` link the spine without prose-matching. A criterion whose source is neither the SOW nor a skill must point to an **ADR** (`meta-adr-authoring`). - **At T0** (marketing/prototype) skip IDs except on money/auth/data criteria. - **Mockups:** before a mockup set is "done", run the token-lint so a typo'd `var(--token)` (which renders as *nothing* — invisible breakage) is caught: `node /scripts/mockup-token-lint.mjs docs/specs//mockups src/app/globals.css`. Subagents reintroduce this constantly — put the lint in their return criteria. ## Bespoke public-facing design — extra gates When the spec covers a bespoke public page (marketing home, storefront, customer-facing screen), three extra gates apply (internal/admin screens are exempt — they're deliberately templated): - **Research references first.** Before designing, pull live references and extract specific moves — see `frontend-public-site-conventions` → "Research live references before you design." Cite them in the Approach section. A bespoke layout is a *derived* decision, not a default you fell into; skipping this is what produces a generic first draft. - **Brand values carry provenance.** Every color/font the spec states must trace to `BRAND-GUIDE.md` — tagged `extracted from live CSS {url} {date}` (computed value, not a guess), `from client brand book`, `Persimmon scaffold default — provisional`, or `human-blocked — pending client`. A bare hex/font with no provenance is invented — fix it or mark it human-blocked. Never log a color/font that isn't in the captured brand (a past project shipped an invented navy + a font that wasn't on the site). - **Content parity (redesigns).** Every real content block on the old site (from `client-onboarding`'s inventory — including content trapped in PDFs/images) maps to the new design, or is explicitly flagged "dropped — confirm with client." Forward traceability for content, the way SOW coverage is for scope. Generic mockups silently drop what makes the business specific. Definition of done for the page itself: it passes the `frontend-public-site-conventions` "system test" (the anti-AI-tell self-audit). Hand references + the brand guide to any subagent that builds a screen — they don't inherit this. ## Output An approved spec at `docs/specs/YYYY-MM-DD-{topic}.md` in the client repo. On approval, hand off to `workflow-plan`. ## When NOT to use Trivial edits (copy, one-line Tailwind, dependency bumps, typos) bypass — go straight to the relevant domain mother. ## Relationship to other skills Followed by `workflow-plan`. The spec is the source of truth `workflow-code-review` checks against.