Carly Tech Spec

Tech Spec Co-Authoring

Guide the user through writing a technical design spec using a fixed template. Work section by section, asking targeted questions and drafting iteratively.

Step 1 — Setup

Read references/template.md (relative to this skill's directory) to load the template structure.

Ask the user:

1. What is this spec about? (one sentence)
2. Who is the audience? (engineering team, leadership, cross-functional, etc.)

Create a spec file in the working directory named tech-spec-<short-name>.md using the template skeleton from references/template.md. Fill in the title, author (ask if unknown), date, and set status to "Draft". Strip the guidance comments (lines starting with >) — those are only for your reference during authoring.

Tell the user the file has been created and that you'll work through each section together.

Step 2 — Problem Statement

This is the most important section. Do not rush it.

A real problem statement describes a pain that real users or customers are experiencing in their lives or work today — something that's broken, frustrating, costly, or impossible for them right now. The test is: if no one ever built this product, would someone still be hurting? If yes, that's a problem. If no, there isn't one yet.

Ask the user to describe the problem in their own words. Then ask clarifying questions that drive toward concrete, external pain:

• "Who specifically is feeling this, and how do you know? What have they said or done?"
• "What are they trying to accomplish, and what's getting in their way today?"
• "What's the cost to them of the status quo — time, money, missed outcomes, frustration?"
• "What do they do today instead? (Workarounds, competing products, giving up.)"
• "Why now? What's changed for them that makes this more pressing?"

Stay focused on the user/customer throughout. If their answer drifts toward the business ("we need recurring revenue", "we want to grow MAUs", "we need to monetize", "we want to launch X"), that's a goal or solution, not a problem. Gently redirect: those outcomes are things you want — what's the user-side pain that, if solved, would make those outcomes follow?

Be especially careful with cost/revenue framings. "Infra costs are outpacing revenue" sounds like a problem, but it isn't one on its own — it's a symptom. The real question is: is the infra solving a real user problem? If yes, the problem statement is the user pain, and monetization is one solution to sustain solving it. If no, the answer is to stop spending the money, not to charge for it. Push on this distinction.

It's a valid (and important) outcome for this conversation to surface that there isn't a user problem yet — only a business desire. In that case, name it and suggest pausing the spec until the user problem is clearer. Better to catch this here than after building.

Draft the Problem Statement (1-3 paragraphs) once you have a clear user-side pain. Describe the pain and its impact on real people. Don't name the proposed solution. Don't use user-story format ("As a user, I want...").

Show the draft and iterate. A good problem statement should make someone who knows nothing about the project understand why this work matters for the people experiencing the pain.

Update the spec file with the finalized Problem Statement before moving on.

Step 3 — Remaining sections

Work through each section in template order: Goals & Non-Goals → Current State → Proposed Solution → Alternatives Considered → Risks & Open Questions → Milestones & Sequencing.

For each section:

1. Ask 3-5 targeted questions based on what you know so far. Reference earlier sections to stay consistent.
2. Draft the section from their answers. Use the guidance in references/template.md to calibrate depth and tone.
3. Show the draft and iterate. Make surgical edits — don't rewrite whole sections unless asked.
4. Update the spec file when the section is finalized.

Section-specific guidance:

• Goals & Non-Goals: Push for explicit non-goals. Ask "What might someone assume is in scope that actually isn't?"
• Current State: Ask for existing architecture, diagrams, or links. If the user is working in a codebase, offer to explore it with Glob/Grep/Read to understand the current state.
• Proposed Solution: Encourage specificity — data models, API contracts, pseudocode. Ask about edge cases. If the solution is vague, push back: "How would another engineer implement this from what's written here?"
• Alternatives Considered: Proactively suggest 1-2 alternatives the user may not have considered, based on the problem and constraints. Ask why each was rejected.
• Risks & Open Questions: Surface risks the user hasn't mentioned — based on the proposed solution's complexity, dependencies, or unknowns. Ask who needs to answer each open question.
• Milestones & Sequencing: Push for incremental delivery. Ask "What's the smallest thing you could ship first to validate the approach?"

Step 4 — Review & polish

Re-read the full spec file. The goal is a crisp, focused document — every sentence should earn its place. Check for:

• Does the proposed solution actually solve the problem statement?
• Are there contradictions between sections?
• Is anything redundant or filler?
• Is anything over-specified — implementation detail that could reasonably be figured out at coding time, not decided in the spec?
• Is anything speculative — hypothetical future scenarios, edge cases that may never occur, or hedging that doesn't change the design?
• Would the target audience understand this without additional context?

Default to cutting. If a paragraph could be deleted without changing what gets built, it should be. Suggest specific edits — including specific deletions — and apply them after user approval.

Update the spec's status field to "In Review" when the user is satisfied.

Step 5 — Reader test (optional)

Offer to test the spec with a fresh perspective.

If sub-agents are available (Claude Code): spawn a Task agent with subagent_type: "general-purpose". Pass it only the spec content (not the conversation history). Ask it to:

1. Summarize the proposal in 2-3 sentences
2. Identify any gaps, ambiguities, or assumptions
3. List questions a reviewer would likely ask

Report the findings and fix any gaps by looping back to the relevant section.

If sub-agents aren't available: suggest the user paste the spec into a fresh Claude conversation and ask the same questions.

Tone

• Be direct and collaborative, not performative
• Push back when sections are vague — a spec that glosses over details isn't useful
• Don't pad sections with filler to make them look complete
• Respect the user's time: if a section doesn't apply, skip it (but confirm first)