| name | project-planning |
| description | Use this skill whenever a user wants to plan a project, create a project spec, write a project brief, scope out work, define requirements, or kick off any initiative of meaningful complexity. Trigger on phrases like "help me plan", "let's scope out", "I want to build/create/launch X", "write a spec for", "project kickoff", "define requirements", or any time the user describes a goal that will require coordinated effort. This skill ensures thorough discovery via clarifying questions and produces a living spec document that gets updated incrementally throughout the conversation. Always use this skill even if the user just says "let's plan a project" without more detail — the discovery phase will gather what's needed.
|
Project Planning Skill
This skill guides Claude through a structured project planning conversation that
produces a high-quality, living spec document. The spec is written and updated
incrementally — never all at once at the end.
Core Principles
- Ask before assuming. Never invent scope. Always surface ambiguity as a
question.
- Write back to the spec continuously. After each meaningful exchange,
update the spec file. The user should be able to stop at any point and have
a useful document.
- Single source of truth. All decisions, requirements, and open questions
live in the spec. Refer back to it, don't restate things from memory.
- Scope creep prevention. When new ideas arise mid-conversation, flag them
as "Out of Scope / Future" rather than silently expanding the project.
- SMART goals. Objectives must be Specific, Measurable, Achievable,
Relevant, and Time-bound.
Workflow
Phase 1: Discovery (Clarifying Questions)
Before writing anything, ask targeted questions to understand the project.
Batch related questions together — don't ask one at a time. Aim for 2–3 rounds
of questions max before starting the spec draft.
Round 1 — The Big Picture (always ask these):
- What is the goal? What does success look like in concrete terms?
- Who are the key stakeholders and end users?
- What's the rough timeline or deadline?
- Are there known constraints (budget, team size, tech stack, regulatory)?
Round 2 — Depth (ask based on Round 1 answers):
- What's explicitly out of scope?
- What are the top 3 risks or unknowns?
- What does the team already have (existing systems, prior work, assets)?
- Who is the decision-maker / project owner?
Round 3 — Validation (ask only if still unclear):
- Are there similar projects or references to learn from?
- What's the definition of "done" for Phase 1?
- What would cause this project to be cancelled?
Do not ask all questions at once. Read the user's level of detail and skip
questions that are clearly already answered.
Phase 2: Write the Spec (Incremental)
Create the spec file at the start of Phase 2. Use the path:
/mnt/user-data/outputs/project-spec.md
Populate sections as information becomes available. Use [TBD] placeholders
for unanswered sections — do not leave them blank. After each major piece of
information is confirmed, update the file using str_replace.
Spec structure (see references/spec-template.md for the full template):
# Project Spec: [Project Name]
_Last updated: [date]_
## 1. Overview
## 2. Goals & Success Metrics
## 3. Stakeholders
## 4. Scope
### In Scope
### Out of Scope / Future
## 5. Requirements
### Functional Requirements
### Non-Functional Requirements
## 6. Timeline & Milestones
## 7. Risks & Mitigations
## 8. Open Questions
## 9. Decisions Log
Phase 3: Iterative Refinement
As the conversation continues, keep the spec live:
- When the user clarifies something → update the relevant section
- When a new requirement emerges → add it to Functional or Non-Functional
Requirements
- When something is deferred → move it to Out of Scope / Future
- When a decision is made → log it in the Decisions Log with a short rationale
- When a question is resolved → remove it from Open Questions (or move to
Decisions Log)
Announce spec updates briefly: "I've added that to the spec under Risks."
Phase 4: Wrap-Up
When the user signals they're done (or after a natural stopping point):
- Do a final pass over the spec — check for
[TBD] items and ask about
any that are blocking
- Present the spec file using
present_files
- Offer a brief summary: what's solid, what's still open
Guardrails
- Never expand scope silently. If a user adds a new idea, ask: "Should
I add this to scope, or log it as a future consideration?"
- Avoid documentation debt. Don't let more than 2–3 exchanges pass without
updating the spec.
- Flag contradictions. If new information conflicts with something already
in the spec, surface it: "This seems to conflict with the deadline we noted
earlier — want to revisit that?"
- Keep requirements testable. Vague requirements like "fast" or "easy to
use" should be challenged: "Can we define a specific performance target?"
Reference Files
references/spec-template.md — Full blank spec template to copy at project
startreferences/questions-bank.md — Extended question bank by project type
(software, marketing, operations, research)
