create-tdd

name	create-tdd
description	Write a GoodParty Technical Design Doc (TDD) for a big-rock feature: a human-reviewable design of the system changes, posted to the ClickUp TDD folder, with deeper detail split into an Implementation Notes subpage. Use when the user wants to design a feature, write a tech design / design doc / TDD, or turn a scoped problem into a reviewable technical design. Not for small features or bugs.

Write a GoodParty Technical Design Doc

A TDD is the artifact the team reviews synchronously, in one ~1-hour call, aiming for one round. It is the primary quality gate for big technical decisions (code review is mostly automated here). That sets everything below.

The standard is written down in How We Build Features, and the agent's job is to comply with it, not fight it: "a document a human being can read completely in 15 minutes," and "a TDD is not an implementation plan; it's a description of the system changes being proposed, with the key choices highlighted." The named failure mode there is "a 15-page, fully AI-generated TDD" and "AI-generated technical design docs that hide the absence of thought." Left unchecked you will produce exactly that. Don't.

Gate: is this even a TDD?

TDDs are for big rocks only. Rough test (theirs): does the work touch more than one system, or more than one team's surface area? If no (a one-screen UI change, a bug, a small feature), there is no TDD. Say so and route it to the pod's normal queue. Don't manufacture ceremony.

Process (the human owns the thinking)

1. Brainstorm first. If the superpowers:brainstorming skill is available, run it before drafting. Never produce the full doc before the dialogue; that's how you get the 15-page nobody-thought-about-it doc.
2. Surface the forks; let the human decide. Your value is finding the real design decisions and arguing the tradeoffs, not resolving them. Put load-bearing forks to the human as explicit questions (use AskUserQuestion), recommend a direction with reasoning, and let them choose. The human mind is the point of a TDD; you are assistance.
3. Draft, then cut. First pass tends long. Cut toward the 15-minute gate (below) by relocating depth to the Implementation Notes subpage, never by deleting it.

The Orange bias (apply to every component)

GoodParty is a pre-PMF startup. On a Red→Violet scale (Red is "one dev yoloing vibe-code to prod," Violet is "AWS/Google battle-tested and bulletproof") we are at Orange: lean, simple, reuse what exists. For each piece of the design ask "what's the simplest thing that works at Orange?"

• Strongly prefer reusing existing infrastructure over introducing new.
• Any new infra, dependency, table, or service must be explicitly justified.
• Hide risk behind flags / manual cohorts; ship dark, validate, then ramp.
• If you're taking on tech debt, name it out loud in the doc.
• Make reuse-vs-new visible so a reviewer can see where complexity is being added.

What goes in each section

Follow the existing template (don't restructure it). What belongs in each:

• Summary: 2-4 sentences, prose. What we're building and why. No decision list, no bullets. Link the prototype, the scope doc, and any related TDDs (e.g. a dependency design).
• Scope / Not in this doc: what this covers and what's deferred or owned elsewhere. If a separate scope doc exists, link it and note only the deltas. If the source PRD or scope doc phases delivery (MVP, Phase 1/2, dated checkpoints), carry those milestones through here so they survive into epic creation; if it specifies none, don't invent any.
• Proposed Solution: the bulk of the doc. Decompose into the 2-5 real subproblems and give each its own subsection. Organize by subproblem, never by repo/stack. Per subproblem, include the load-bearing detail and nothing past the decision:
  • Full Prisma models for new/changed tables (always; schema is design).
  • The shape of any contract crossing a service boundary (the shape, not every field; field-level contracts go to the subpage).
  • The key choice and why. A diagram where the data flow isn't obvious.
• API surface: a single table of new endpoints: method & path | purpose | consumers | MCP-enabled?. Cheap to write, and it makes the access patterns legible at a glance. Mark which endpoints are exposed as MCP tools for agents.
• Key Takeaways: bulleted. The load-bearing decisions a reviewer must leave with. Decisions live here, not in the Summary.
• Alternatives Considered: work from 2-3 genuinely distinct approaches before settling, not just a record of what you rejected. Distinct means a real fork (sync in the request path vs queued async; extend an existing table vs a new one), not bikeshedding (library X vs Y). A short paragraph each: what it is and why it lost. The recommendation needs reasoning a reviewer can argue with, not just a vote. If there is only one reasonable approach, say so explicitly in one line; manufactured options waste the reviewer's time and dilute trust.
• Open Questions: genuine unknowns, and things deliberately deferred to implementation. Reviewers add to this during the call.

Cross-cutting prompts (answer each, even if N/A)

Reviewers consistently ask about these four. Answer each in whichever section fits, as prose, not mandatory tables. "N/A because " is a valid answer; silence is not.

• Inputs and outputs: what flows in (requests, queue messages, user actions) and out (responses, events emitted, persisted state, side effects). Name which inputs are user-controlled.
• DB changes: the Prisma models rule covers the change case; when there is no DB change, say so and why.
• Failure and recovery: what failure looks like, its blast radius, and how we recover (bad deploy, external API outage, queue backlog). A stateless read-only feature can say exactly that in one sentence.
• Data flow: the diagram plus one prose paragraph of the flow. For a simple flow a mermaid block in the doc is enough; for anything bigger, author scratch/<feature>/<feature>-data-flow.drawio.xml (plain XML, renders in diagrams.net or the VS Code Draw.io extension) as the editable source of truth and attach an export to the ClickUp page. One canonical diagram: services, data stores, queues, external APIs, and the user, with every edge labeled by what flows. No internal classes.

Two tiers: the TDD and the Implementation Notes subpage

The tension: trimming for reviewability would throw away detail that's useless in review but essential during planning. Solution: a second page. Relocate, never delete.

• Main TDD (the review artifact): Prisma models, contract shapes, the data-flow diagram, the API surface table, the decisions, the alternatives, and the reused-vs-new callouts.
• Implementation Notes (a ClickUp child page of the TDD): full field-level contracts, validation/upsert step lists, edge-case handling, the template's "Optional" material (metrics, alerts, "should never happen," cost estimates, abuse prevention, example test sets), and detailed prompt designs. This is also where reviewers "drop into" when a question goes deeper than the TDD. Also include a Codebase context section carrying what you learned during recon, so the planning agent doesn't re-derive it: the existing patterns to extend and the seam where new code lands, each with a short (5-15 line) excerpt of the real code (a file path alone doesn't transfer the pattern), plus where similar tests live and any pain points to avoid (deprecated dirs, in-progress migrations). Excerpts come from the actual repo scan, never from memory.
• Omit (or subpage) unless genuinely novel: UI layout and component detail. Specify a UI interaction only when the interaction model itself is the hard part. Never restate what the code already shows. Never write implementation that pre-empts the planning phase.

Altitude rule: specify the decision and its constraints, not the implementation. If a competent engineer plus a planning agent could derive it, leave it out. Under- specified is acceptable; over-specified is the failure mode.

Length and style gate

• 15-minute read. As a heuristic, keep the main TDD to ~2,500 prose words or fewer (excluding code blocks and diagrams). Before declaring done, estimate the prose word count and reading time; if it's over, move depth to Implementation Notes.
• No em dashes (org style). Terse bullets, bold sub-labels, complete sentences.
• Write for a human reviewer skimming on a deadline, not for a parser.

Where it goes (ClickUp)

TDDs live in the Technical Design Docs folder: parent page 2ky4jq2q-81493, in doc 2ky4jq2q-20493, workspace 90132012119. The section template is page 2ky4jq2q-81513 (read it for the current skeleton).

Keep a local working copy under scratch/<feature>/ and mirror to ClickUp through the ClickUp MCP server (configured in .mcp.json, authorized via OAuth, see docs/mcp.md). There is no ClickUp API token in this repo; don't shell out to the REST API.

ClickUp is read-only by default (docs/mcp.md): reads are free, but ask the user before creating or updating any page, and read the remote page first before an update so you can surface any human edits instead of clobbering them.

• Read the template page 2ky4jq2q-81513 for the current skeleton.
• Create the TDD page in the folder: a ClickUp MCP create-page call with parent_page_id = the TDD folder (2ky4jq2q-81493).
• Create the Implementation Notes page as a child of the TDD page (parent_page_id = the TDD page id from the step above). Cross-link the two.
• Update a page: read it, diff against your local draft, confirm with the user, then update.

Before declaring done

• Big rock confirmed; otherwise no TDD.
• Brainstormed with the human; the load-bearing forks were their calls.
• Summary is prose; the decisions are in Key Takeaways.
• Proposed Solution is decomposed by subproblem.
• Prisma models, contract shapes, a diagram (if flow is non-trivial), and the API surface table are present.
• Alternatives are genuinely distinct with a reasoned recommendation, or explicitly collapsed to one.
• The four cross-cutting prompts (inputs/outputs, DB changes, failure/recovery, data flow) are each answered or explicitly N/A with a reason.
• Milestones from the source PRD/scope doc carried through; none invented.
• Reuse-vs-new is visible; any new infra is justified (Orange).
• Deep detail was moved to Implementation Notes, not deleted; Implementation Notes carries Codebase context with real code excerpts.
• Main TDD is ~15 minutes / ~2,500 prose words or fewer; no em dashes.
• Posted to the TDD folder; Implementation Notes subpage created and cross-linked.