diff --git a/commands/plan-issues.md b/commands/plan-issues.md index 7b46fc5..ca3ab34 100644 --- a/commands/plan-issues.md +++ b/commands/plan-issues.md @@ -10,39 +10,41 @@ argument-hint: @~/.claude/skills/issue-writing/SKILL.md @~/.claude/skills/vision-management/SKILL.md -1. **Check vision context**: If `vision.md` exists, read it to understand current goals and focus -2. **Understand the feature**: Analyze what "$1" involves -3. **Explore the codebase** if needed to understand context -4. **Break down** into discrete, actionable issues: +1. **Check vision context**: If `vision.md` exists, read it to understand personas, jobs to be done, and goals +2. **Identify persona**: Which persona does "$1" serve? +3. **Identify job**: Which job to be done does this enable? +4. **Understand the feature**: Analyze what "$1" involves +5. **Explore the codebase** if needed to understand context +6. **Break down** into discrete, actionable issues: - Each issue should be independently completable - Clear dependencies between issues - Appropriate scope (not too big, not too small) -5. **Present the plan** (include vision alignment if vision exists): +7. **Present the plan** (include vision alignment if vision exists): ``` ## Proposed Issues for: $1 - Vision Alignment: Supports [Goal N: description] + For: [Persona name] + Job: "[Job to be done this enables]" + Supports: [Milestone/Goal name] 1. [Title] - Brief description Dependencies: none - Supports: Goal N 2. [Title] - Brief description Dependencies: #1 - Supports: Goal N 3. [Title] - Brief description Dependencies: #1, #2 - Supports: Goal N ``` - If the feature doesn't align with any vision goal, note this and ask if: - - The vision should be updated to include this as a goal + If the feature doesn't align with any persona/job/goal, note this and ask if: + - A new persona or job should be added to the vision + - A new milestone should be created - This should be added as a non-goal - Proceed anyway (with justification) -6. **Ask for approval** before creating issues -7. **Create issues** in dependency order (blockers first) -8. **Link dependencies** using `tea issues deps add ` for each dependency -9. **Present summary** with links to created issues and dependency graph +8. **Ask for approval** before creating issues +9. **Create issues** in dependency order (blockers first) +10. **Link dependencies** using `tea issues deps add ` for each dependency +11. **Present summary** with links to created issues and dependency graph diff --git a/commands/vision.md b/commands/vision.md index 93a16d4..fe3cfb3 100644 --- a/commands/vision.md +++ b/commands/vision.md @@ -25,9 +25,15 @@ Issues are assigned to milestones. Progress is visible through milestone complet 2. **If no vision exists**: - Ask the user if they want to create one - - Guide them through the philosophy: purpose, principles, non-goals + - Guide them through defining: + 1. **Personas**: Who are we building for? (2-4 specific personas) + 2. **Jobs to be done**: What are they trying to achieve? + 3. **The problem**: What pain points exist today? + 4. **The solution**: How does this product address their jobs? + 5. **Guiding principles**: What beliefs guide decisions? + 6. **Non-goals**: What are we explicitly NOT doing? - Create `vision.md` (do NOT include goals/progress - that's milestones) - - Ask about initial goals and create them as Gitea milestones + - Ask about initial goals tied to personas/jobs, create as Gitea milestones 3. **If vision exists**: - Display the vision philosophy from `vision.md` @@ -54,15 +60,25 @@ Issues are assigned to milestones. Progress is visible through milestone complet ## Output Format ``` +## Who We Serve + +- **[Persona 1]**: [Brief description] +- **[Persona 2]**: [Brief description] + +## What They're Trying to Achieve + +- "[Job to be done 1]" +- "[Job to be done 2]" + ## Vision -[Summary of vision.md purpose/principles] +[Summary of problem/solution from vision.md] ## Goals (Milestones) -| Goal | Progress | Due | -|------|----------|-----| -| [title] | 3/5 issues | [date] | +| Goal | For | Progress | Due | +|------|-----|----------|-----| +| [title] | [Persona] | 3/5 issues | [date] | ## Current Focus @@ -71,8 +87,10 @@ Issues are assigned to milestones. Progress is visible through milestone complet ## Guidelines -- vision.md is the stable "why" document - update rarely -- Milestones are the actionable goals - create/close as needed +- vision.md is the stable "why" and "who" document - update rarely +- Personas and jobs to be done are foundational - everything traces back to them +- Milestones are actionable goals - each should serve a specific persona's job - Assign issues to milestones to track progress -- Use milestone descriptions for success criteria +- Use milestone descriptions for: persona, job, success criteria - Due dates on milestones are optional but help prioritization +- If you can't tie work to a persona/job, question whether it should be done diff --git a/skills/vision-management/SKILL.md b/skills/vision-management/SKILL.md index 3eb503f..a95eb01 100644 --- a/skills/vision-management/SKILL.md +++ b/skills/vision-management/SKILL.md @@ -22,39 +22,81 @@ The vision system has two layers: ## Vision Document Structure -The vision.md file should contain the stable "why" - not progress tracking: +The vision.md file should contain the stable "why" and "who" - not progress tracking: ```markdown # Vision +## Who We Serve (Personas) +The people we're building for and what characterizes them. + +- **Persona Name**: Brief description of who they are, their context, constraints + +## What They're Trying to Achieve (Jobs to Be Done) +The outcomes our personas are trying to accomplish - in their words. + +- "Help me [achieve outcome] without [pain point]" +- "Help me [do thing] so I can [benefit]" + ## The Problem -What problem does this product solve? Who benefits? +Current pain points that prevent our personas from achieving their jobs. ## The Solution -How does this product solve the problem? +How this product addresses the jobs to be done. ## Guiding Principles Core beliefs that guide decisions. ## Non-Goals -What we're explicitly NOT doing. +What we're explicitly NOT doing (and why). ``` Do NOT include goals, progress, or focus in vision.md - that's what milestones are for. +## Defining Personas + +Good personas are: +- **Specific**: Not "developers" but "solo developers shipping MVPs" +- **Characterized**: Include constraints, context, priorities +- **Limited**: 2-4 personas max, or you're building for everyone (no one) + +| Bad | Good | +|-----|------| +| "Users" | "Solo developer shipping side projects on evenings/weekends" | +| "Developers" | "Small team lead coordinating 2-5 engineers" | +| "Companies" | "Early-stage startup with no dedicated DevOps" | + +## Defining Jobs to Be Done + +Jobs should be: +- **Outcome-focused**: What they want to achieve, not what they do +- **In their voice**: How they'd describe it, not technical jargon +- **Pain-aware**: Include what's hard about it today + +Format: "Help me [outcome] without [pain]" or "Help me [action] so I can [benefit]" + +| Bad | Good | +|-----|------| +| "Git integration" | "Help me commit and push without remembering git commands" | +| "Issue tracking" | "Help me know what to work on next without checking 5 tools" | +| "Code review" | "Help me catch bugs before they ship without slowing down" | + ## Creating a Vision When no vision exists: -1. **Identify the problem**: What pain point does this solve? -2. **Define the solution**: How does the product address it? -3. **Set guiding principles**: What beliefs guide decisions? -4. **Document non-goals**: What are you explicitly NOT doing? -5. **Create initial milestones**: 3-5 measurable goals +1. **Define personas**: Who are we building for? (2-4 specific personas) +2. **Identify jobs to be done**: What are they trying to achieve? +3. **Articulate the problem**: What pain points prevent them from achieving their jobs? +4. **Define the solution**: How does the product address these jobs? +5. **Set guiding principles**: What beliefs guide decisions? +6. **Document non-goals**: What are you explicitly NOT doing? +7. **Create initial milestones**: 3-5 measurable goals tied to personas/jobs ### Good Goals (Milestones) - Specific and measurable +- Tied to a persona and job to be done - Outcome-focused (not activity-focused) - Have clear success criteria in the description @@ -64,6 +106,25 @@ When no vision exists: | "Better UX" | "User can complete checkout in under 60 seconds" | | "More features" | "Support 3 export formats (CSV, JSON, PDF)" | +### Tying Milestones to Personas + +Each milestone should clearly serve a persona's job to be done: + +``` +Milestone: "Automate routine git workflows" +For: Solo developer +Job: "Help me commit and push without remembering git commands" +Success: /commit, /pr commands handle 80% of git workflows +``` + +Include persona context in milestone descriptions: +```bash +tea milestones create --title "Automate routine git workflows" \ + --description "For: Solo developer +Job: Ship without context switching to git commands +Success: /commit and /pr commands handle 80% of workflows" +``` + ## Managing Goals with Milestones ```bash @@ -98,18 +159,24 @@ Progress is automatically tracked through open/closed issue counts. When creating or reviewing issues: -1. **Check goal alignment**: Does this issue support a milestone? -2. **Assign to milestone**: Link the issue to the relevant goal -3. **Prioritize by focus**: Issues in priority milestones get worked first -4. **Flag misalignment**: Issues without a milestone need justification +1. **Check persona alignment**: Which persona does this serve? +2. **Check job alignment**: Which job to be done does this enable? +3. **Check goal alignment**: Does this issue support a milestone? +4. **Assign to milestone**: Link the issue to the relevant goal +5. **Prioritize by focus**: Issues in priority milestones get worked first +6. **Flag misalignment**: Issues without clear persona/milestone need justification + +Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]." ### Identifying Gaps -Compare milestones to current backlog: +Compare vision to current work: -- Which milestones have no issues? -- Which milestones have stalled (no recent progress)? -- Are there issues without a milestone? +- **Underserved personas**: Which personas have few milestones/issues? +- **Unaddressed jobs**: Which jobs to be done have no work toward them? +- **Empty milestones**: Which milestones have no issues? +- **Stalled milestones**: Which milestones have no recent progress? +- **Orphan issues**: Are there issues without a milestone? ## Connecting Retros to Vision