diff --git a/skills/vision-management/SKILL.md b/skills/vision-management/SKILL.md index a95eb01..f5e7ff9 100644 --- a/skills/vision-management/SKILL.md +++ b/skills/vision-management/SKILL.md @@ -1,123 +1,175 @@ --- name: vision-management -description: Create, maintain, and evolve a product vision. Use when initializing a vision, updating goals, aligning work with vision, or connecting learnings to vision refinement. +description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction. --- # Vision Management -How to create, maintain, and evolve a product vision for continuous improvement. +How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product). ## Architecture -The vision system has two layers: +| Level | Document | Purpose | Command | Location | +|-------|----------|---------|---------|----------| +| **Organization** | `manifesto.md` | Identity, shared personas, beliefs, principles | `/manifesto` | Architecture repo | +| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repos | +| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo | -| Layer | Purpose | Location | -|-------|---------|----------| -| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root | -| **Milestones** | Goals with progress tracking | Gitea milestones | +Product vision inherits from and extends the organization manifesto. -- **vision.md** is stable - updated rarely when direction changes -- **Milestones** are actionable - created/closed as goals evolve -- **Issues** are assigned to milestones to track progress +--- -## Vision Document Structure +## Manifesto (Organization Level) -The vision.md file should contain the stable "why" and "who" - not progress tracking: +The manifesto defines who we are as an organization. It lives in the architecture repo and applies across all products. + +### Manifesto Structure + +```markdown +# Manifesto + +## Who We Are +Organization identity - what makes us unique. + +## Who We Serve +Shared personas across all products. +- **Persona Name**: Description, context, constraints + +## What They're Trying to Achieve +Jobs to be done at the organization level. +- "Help me [outcome] without [pain]" + +## What We Believe +Core beliefs that guide how we work. +### [Belief Category] +- Belief point +- Belief point + +## Guiding Principles +Decision-making rules that apply everywhere. +1. **Principle**: Explanation + +## Non-Goals +What the organization explicitly does NOT do. +- **Non-goal**: Why +``` + +### When to Update Manifesto + +- **Rarely** - this is foundational identity +- When core beliefs change +- When adding/removing personas served +- When adding non-goals based on learnings + +### Creating a Manifesto + +1. Define organization identity (Who We Are) +2. Identify shared personas (2-4 max) +3. Articulate organization-level jobs to be done +4. Document core beliefs (especially about AI/development) +5. Establish guiding principles +6. Define non-goals + +--- + +## Vision (Product Level) + +The vision defines what a specific product does. It lives in each product repo and extends the manifesto. + +### Vision Structure ```markdown # Vision -## Who We Serve (Personas) -The people we're building for and what characterizes them. +## Who This Product Serves +Product-specific personas (may extend org personas). +- **Persona Name**: Product-specific context -- **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]" +## What They're Trying to Achieve +Product-specific jobs to be done. +- "Help me [outcome] without [pain]" ## The Problem -Current pain points that prevent our personas from achieving their jobs. +Pain points this product addresses. ## The Solution -How this product addresses the jobs to be done. +How this product solves those problems. -## Guiding Principles -Core beliefs that guide decisions. +## Product Principles +Product-specific principles (beyond org principles). ## Non-Goals -What we're explicitly NOT doing (and why). +What this product explicitly does NOT do. ``` -Do NOT include goals, progress, or focus in vision.md - that's what milestones are for. +### When to Update Vision -## Defining Personas +- When product direction shifts +- When adding/changing personas served by this product +- When discovering new non-goals +- After major learnings from retros -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) +### Creating a Product Vision -| 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" | +1. Reference the organization manifesto +2. Define product-specific personas (can extend org personas) +3. Identify product-specific jobs to be done +4. Articulate the problem this product solves +5. Define the solution approach +6. Set product-specific principles (if any) +7. Document product non-goals +8. Create initial milestones -## 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 +## Relationship: Manifesto → Vision -Format: "Help me [outcome] without [pain]" or "Help me [action] so I can [benefit]" +``` +Manifesto (org) Vision (product) +├── Shared Personas → Product Personas (more specific) +├── Org Jobs → Product Jobs (subset/extension) +├── Beliefs → (inherited, not duplicated) +├── Principles → Product Principles (additional) +└── Non-Goals → Product Non-Goals (additional) +``` -| 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" | +### Inheritance Model -## Creating a Vision +- **Personas**: Product personas can be more specific versions of org personas +- **Jobs**: Product jobs should trace back to org-level jobs +- **Beliefs**: Inherited from manifesto, not duplicated in vision +- **Principles**: Product can add specific principles; org principles apply automatically +- **Non-Goals**: Product adds its own; org non-goals apply automatically -When no vision exists: +### Example -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 +**Manifesto** (organization): +```markdown +## Who We Serve +- **Solo Developer**: Individual shipping side projects, time-constrained +``` -### Good Goals (Milestones) +**Vision** (product - e.g., CLI tool): +```markdown +## Who This Product Serves +- **Solo Developer (CLI user)**: Uses terminal daily, prefers keyboard over GUI +``` + +The product persona extends the org persona with product-specific context. + +--- + +## Milestones (Goals) + +Milestones are product-level goals that track progress toward the vision. + +### Good 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 +- Include success criteria in description -| Bad | Good | -|-----|------| -| "Improve performance" | "Page load under 2 seconds" | -| "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 @@ -125,35 +177,14 @@ Job: Ship without context switching to git commands Success: /commit and /pr commands handle 80% of workflows" ``` -## Managing Goals with Milestones +### Milestone-to-Vision Alignment -```bash -# List milestones with progress -tea milestones -tea milestones -f title,items_open,items_closed,state +Every milestone should trace to: +- A persona (from vision or manifesto) +- A job to be done (from vision) +- A measurable outcome -# Create a new goal -tea milestones create --title "Automate repetitive workflows" \ - --description "Success: 80% of routine tasks handled by slash commands" - -# View issues in a milestone -tea milestones issues "Automate repetitive workflows" - -# Close a completed goal -tea milestones close "Automate repetitive workflows" -``` - -### Assigning Issues to Milestones - -When creating issues, assign them to the relevant milestone: - -```bash -tea issues create --title "Add /commit command" \ - --description "..." \ - --milestone "Automate repetitive workflows" -``` - -Progress is automatically tracked through open/closed issue counts. +--- ## Aligning Issues with Vision @@ -161,50 +192,49 @@ When creating or reviewing issues: 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? +3. **Check milestone alignment**: Does this issue support a goal? 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 vision to current work: - - **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? +- **Orphan issues**: Issues without a milestone need justification -## Connecting Retros to Vision - -After a retrospective: - -1. **Review learnings**: Any that affect the vision or goals? -2. **Milestone changes**: Should any goals be added, closed, or modified? -3. **Non-goal additions**: Did we learn something to add to vision.md? -4. **Progress check**: Did completed work close any milestones? - -### Retro-to-Vision Questions - -- "Did this work reveal a new goal we should add as a milestone?" -- "Did we learn something that should become a non-goal in vision.md?" -- "Should we close or modify any milestones based on what we learned?" -- "Are any milestones ready to close?" +--- ## Continuous Improvement Loop ``` -Vision → Milestones → Issues → Work → Retro → (Vision/Milestones updated) +Manifesto → Vision → Milestones → Issues → Work → Retro → (updates) + ↓ + Architecture repo issues + ↓ + Encoded into learnings + + skills/commands/agents ``` -1. **Vision** defines why and principles (stable) -2. **Milestones** define measurable goals -3. **Issues** are work items toward those goals -4. **Work** implements the issues -5. **Retros** capture learnings -6. **Updates** refine vision and create/close milestones +1. **Manifesto** defines organizational identity (very stable) +2. **Vision** defines product direction (stable) +3. **Milestones** define measurable goals (evolve) +4. **Issues** are work items toward goals +5. **Work** implements the issues +6. **Retros** create issues on architecture repo +7. **Encoding** turns insights into learnings and system improvements -The vision is stable. The milestones evolve as you learn and achieve goals. +--- + +## Quick Reference + +| Question | Answer | +|----------|--------| +| Where do shared personas live? | `manifesto.md` in architecture repo | +| Where do product personas live? | `vision.md` in product repo | +| Where do beliefs live? | `manifesto.md` only (inherited) | +| Where do goals live? | Gitea milestones (per repo) | +| What command for org vision? | `/manifesto` | +| What command for product vision? | `/vision` | +| What repo for learnings? | Architecture repo |