Technical Planning Templates
This folder contains templates for documenting technical decisions before implementation begins. There are two tiers: full TDD templates for major projects and a lightweight design doc for smaller work.
Which Template Should I Use?
| Scope of Work | Template | Time to Fill Out |
|---|---|---|
| New platform, major migration, new system build — work that introduces new architecture, involves multiple stakeholders, or makes decisions that are expensive to reverse | Full TDD (Data or AI & Platform) | 2-4 hours |
| Feature, enhancement, or non-trivial change to an existing project — a few days to a couple of weeks of work where the system already exists | Lightweight Design Doc | 30-60 minutes |
| Bug fix, config change, copy update — straightforward work with an obvious path | No template needed — just put the context in the Linear ticket | — |
When in doubt: start with the lightweight doc. If you find yourself writing multiple pages about architecture tradeoffs and needing appendix variants, upgrade to the full TDD.
Templates
| Template | Team | Use When |
|---|---|---|
| TDD Data Template | Data Platform | Warehouse migrations, ETL/ELT pipelines, dbt modeling, BI rollouts, CDP/activation, data quality initiatives |
| TDD AI & Automation Template | AI, Automation & Platform Engineering | RAG pipelines, agentic systems, MCP servers, workflow automation (n8n, Windmill), API/backend services, frontend features, fine-tuning, AI copilots, LLM integrations |
| Lightweight Design Doc | Any | Features, enhancements, or non-trivial changes to existing projects on either team |
How to Use
Manually
- Copy the relevant template into your client repo or project workspace, or point the agent to this folder.
- Fill in the header / Document Control section.
- Work through the sections — the template guides you through what to write.
- Get a review from the team before implementation starts.
With an AI Planning Agent (Cursor, Codex, etc.)
These templates are designed to work in two directions: an AI agent can help you create the plan, and then a different agent session can execute from it.
See agents.md for full instructions on how AI agents should use these templates. The short version:
- Open the template + agents.md as context in Cursor (or reference them with
@). - Describe what you’re building. The agent will interview you section by section, ask targeted questions, explore the codebase, and draft the doc collaboratively.
- Review the draft. The agent flags gaps and open questions. Resolve them with the agent or with teammates.
- The completed doc serves both audiences: human reviewers approve it, then the Agent Implementation Context / Handoff Brief section gives a coding agent everything it needs to execute.
Template-Specific Notes
Full TDD Templates
- Choose the right Appendix variant for the architecture and modeling/strategy sections. The agent can help you pick.
- Fill the KQA Matrix early — it anchors the entire design to business questions.
- The Agent Handoff Brief section is near the end. Create one per milestone/workstream.
Lightweight Design Doc
- Sections 1-3 are the core. Sections 4-8 can be lighter for simpler work.
- Section 9 (Agent Implementation Context) must be concrete and specific — this is what makes agent execution effective.
Shared Concepts Across the Full TDD Templates
- KQA Matrix (Key Questions & Answers) — ties architecture decisions back to the business questions the system must answer.
- Before / After Impact Scorecard — quantifies the expected improvement and defines how you’ll measure it.
- ADR Index (Architecture Decision Records) — captures trade-offs and rationale so institutional knowledge survives.
- Appendix Variants — pick-one architecture and modeling/strategy patterns so the template stays relevant across different project types.