Initial commit
This commit is contained in:
Zhongwei Li
141
skills/product-manager/README.md
Normal file
141
skills/product-manager/README.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Claude Product Manager Skill
|
||||
|
||||
AI-powered Product Owner assistance for ticket management and refinement across multiple project management systems.
|
||||
|
||||
## What It Does
|
||||
|
||||
When you work with tickets in Linear, GitHub Issues, Local Markdown, or other supported PM systems, this Skill automatically activates to help you:
|
||||
|
||||
- **Create tickets** — Draft well-structured tickets with acceptance criteria from conversations
|
||||
- **Analyze tickets** — Review for completeness, clarity, gaps, and dependencies
|
||||
- **Propose amendments** — Suggest improvements based on code context or new information
|
||||
- **Identify gaps** — Find missing coverage when breaking down epics
|
||||
- **Generate questions** — Create structured refinement session discussion points
|
||||
- **Plan work** — Suggest parallelization strategies and dependency analysis
|
||||
|
||||
## Supported PM Systems
|
||||
|
||||
- **Linear** — Full support via Linear MCP server
|
||||
- **GitHub Issues** — Full support via GitHub CLI (`gh`)
|
||||
- **Local Markdown** — File-based tickets in `docs/tickets/`
|
||||
- Future systems (Jira, Azure Boards, etc.) via extensible connector framework
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install the Plugin
|
||||
|
||||
This skill is part of the **pm-assistant** plugin available in the Claude Code Plugin Marketplace.
|
||||
|
||||
To install, use the marketplace installation command or manually install the plugin from the marketplace.
|
||||
|
||||
### 2. Configure Your PM System
|
||||
|
||||
**For Linear**:
|
||||
1. Follow the [Linear MCP documentation](https://linear.app/docs/mcp) to set up the MCP server
|
||||
2. Authenticate with Linear
|
||||
3. Add `CLAUDE.md` configuration (see step 3)
|
||||
|
||||
**For GitHub Issues**:
|
||||
1. Install GitHub CLI: https://cli.github.com/ or `brew install gh`
|
||||
2. Authenticate: `gh auth login`
|
||||
3. Verify git remote: `git remote get-url origin` (must be a GitHub repository)
|
||||
4. Add `CLAUDE.md` configuration (see step 3)
|
||||
|
||||
**For Local Markdown**:
|
||||
1. Create tickets directory: `mkdir -p docs/tickets`
|
||||
2. Initialize counter: `echo "1" > docs/tickets/.ticket_counter`
|
||||
3. Add `CLAUDE.md` configuration (see step 3)
|
||||
|
||||
### 3. Add Project Context (Required)
|
||||
Create `CLAUDE.md` in your project root to declare which PM system to use:
|
||||
|
||||
**Example for Linear**:
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Project Management
|
||||
- **System**: Linear
|
||||
- **Team Prefix**: PROD
|
||||
- **Project**: Backend Services
|
||||
```
|
||||
|
||||
**Example for GitHub Issues**:
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Project Management
|
||||
- **System**: GitHub-Issues
|
||||
```
|
||||
Note: Repository is auto-detected from git remote origin.
|
||||
|
||||
**Example for Local Markdown**:
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Project Management
|
||||
- **System**: Local-Markdown
|
||||
- **Directory**: docs/tickets
|
||||
```
|
||||
|
||||
The skill will use these settings for all operations in the project.
|
||||
|
||||
## How to Use
|
||||
|
||||
Simply describe what you need with tickets. The Skill activates automatically and works with your configured PM system:
|
||||
|
||||
```
|
||||
Review the tickets for this sprint and identify any gaps
|
||||
|
||||
Create a ticket for implementing dark mode with acceptance criteria
|
||||
|
||||
What are the dependencies between PROD-100 and PROD-110?
|
||||
|
||||
Generate questions for our refinement session on the payment feature
|
||||
|
||||
Suggest improvements to this epic based on the code review
|
||||
```
|
||||
|
||||
The Skill will:
|
||||
1. Fetch relevant tickets from your PM system (Linear, GitHub Issues, or Local Markdown)
|
||||
2. Analyze them using proven patterns
|
||||
3. Present findings or proposals for review
|
||||
4. **Wait for your explicit confirmation** before making changes
|
||||
5. Apply updates and report results
|
||||
|
||||
## Documentation
|
||||
|
||||
- **SKILL.md** — Complete workflow guide and patterns
|
||||
- **assets/ticket_template.md** — Ready-to-use templates
|
||||
- **references/ticket_structure_guide.md** — Quality standards (system-agnostic)
|
||||
- **references/analysis_patterns.md** — Six analysis workflows with examples
|
||||
- **references/refinement_session_guide.md** — Refinement best practices
|
||||
- **connectors/linear.md** — Linear MCP API reference and operations
|
||||
- **connectors/local-markdown.md** — Local Markdown connector documentation
|
||||
- **connectors/local-markdown/setup.md** — Setup instructions for local markdown
|
||||
- **connectors/README.md** — Connector interface and extensibility guide
|
||||
|
||||
## Key Principles
|
||||
|
||||
✅ **Extensible architecture** — PM system-specific code isolated in connectors; supports Linear, GitHub Issues, and Local Markdown
|
||||
✅ **Always proposes before acting** — Shows changes for your review
|
||||
✅ **Requires explicit confirmation** — Never assumes approval
|
||||
✅ **Specific and quoted** — References exact text when identifying issues
|
||||
✅ **Explains rationale** — Shows why changes matter
|
||||
✅ **Reusable patterns** — Analysis and refinement workflows system-agnostic
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Skill not activating | Explicitly ask: "Use the product-manager skill to review these tickets..." |
|
||||
| Team/project not found (Linear) | Add `CLAUDE.md` file with Linear team and project (see Setup step 3) |
|
||||
| Can't find tickets (Linear) | Verify Linear is configured correctly in CLAUDE.md and MCP server is authenticated |
|
||||
| Repository not detected (GitHub) | Verify git remote origin exists and is a GitHub URL: `git remote get-url origin` |
|
||||
| `gh` command not found (GitHub) | Install GitHub CLI: https://cli.github.com/ or `brew install gh` |
|
||||
| Not authenticated (GitHub) | Run `gh auth login` to authenticate with GitHub |
|
||||
| Tickets directory not found (Local Markdown) | Create directory specified in CLAUDE.md: `mkdir -p docs/tickets` |
|
||||
| System not declared | Add `CLAUDE.md` with `System` field set to Linear, GitHub-Issues, or Local-Markdown |
|
||||
|
||||
---
|
||||
|
||||
See **SKILL.md** for comprehensive documentation and workflow examples.
|
||||
396
skills/product-manager/SKILL.md
Normal file
396
skills/product-manager/SKILL.md
Normal file
@@ -0,0 +1,396 @@
|
||||
---
|
||||
name: product-manager
|
||||
description: Product Owner assistance for ticket refinement, epic breakdown, dependency analysis, and backlog management. Use this skill when shaping tickets, analyzing quality, identifying gaps, or generating refinement questions. For ticket data operations (get, list, create, update), the skill delegates to the ticket-assistant agent which supports Linear, Local Markdown, and GitHub Issues.
|
||||
---
|
||||
|
||||
# Product Manager Skill
|
||||
|
||||
## Overview
|
||||
|
||||
This skill enables Product Owner workflows focused on **ticket shaping, structure, and best practices**:
|
||||
- Refine tickets with proper structure and acceptance criteria
|
||||
- Analyze tickets for gaps, clarity, completeness, and dependencies
|
||||
- Break down epics into actionable sub-tickets
|
||||
- Generate meaningful refinement session questions
|
||||
- Propose amendments based on conversation context
|
||||
|
||||
**Ticket Data Operations**: All ticket access and manipulation (get, list, create, update) is delegated to the **ticket-assistant agent**, which handles Linear MCP, Local Markdown, and GitHub Issues operations.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
User Request
|
||||
↓
|
||||
product-manager SKILL (shaping/best practices/analysis)
|
||||
↓ (delegates data operations)
|
||||
ticket-assistant AGENT (Linear MCP / Local Markdown / GitHub CLI CRUD)
|
||||
↓
|
||||
[Linear MCP] or [Markdown Files] or [GitHub CLI]
|
||||
```
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
### 1. Create Tickets from Conversation
|
||||
|
||||
**Scenario**: "Create a ticket for this feature with acceptance criteria" or "Based on the conversation transcript create epic with tickets/ticket"
|
||||
|
||||
**Process**:
|
||||
1. Extract requirements from conversation context
|
||||
2. Use ticket template from `assets/ticket_template.md`
|
||||
3. Structure as simple or complex ticket based on scope
|
||||
4. Apply appropriate type labels (Feature, Bug, Enhancement, etc.)
|
||||
5. Present proposal to user for review
|
||||
6. **Use AskUserQuestion tool for confirmation**: Wait for explicit approval before proceeding
|
||||
7. **After user confirms**: Delegate to ticket-assistant agent to create ticket
|
||||
8. Report created ticket with ID and link
|
||||
|
||||
**Guidelines**:
|
||||
- Refer to `references/ticket_structure_guide.md` for formatting standards
|
||||
- Include acceptance criteria for complex work
|
||||
- Flag open questions when scope is unclear
|
||||
- Suggest dependencies if work relates to existing tickets
|
||||
- **Content focus**: Extract user needs and business value; avoid code snippets
|
||||
- **Include technical details when**:
|
||||
- Explicitly instructed to include them
|
||||
- Deviating from standard conventions or patterns
|
||||
- Non-standard approach requires documentation
|
||||
- Critical technical constraints that impact implementation
|
||||
|
||||
### 2. Propose Ticket Amendments
|
||||
|
||||
**Scenario**: "Are there any wrong assumptions in the ticket?" or "Based on the conversation transcript suggest adjustments to epic XXX-123"
|
||||
|
||||
**Process**:
|
||||
1. Delegate to ticket-assistant agent to fetch existing ticket/epic
|
||||
2. Analyze current state (description, acceptance criteria, scope)
|
||||
3. Cross-reference with provided context (code, conversation, etc.)
|
||||
4. Use patterns from `references/analysis_patterns.md` to identify:
|
||||
- Assumption mismatches
|
||||
- Scope gaps or overreach
|
||||
- Missing edge cases or error handling
|
||||
- Outdated requirements
|
||||
5. Present proposed changes:
|
||||
- "Current state" (quote from ticket)
|
||||
- "Suggested changes" (with rationale)
|
||||
- "Questions for team" (if needed)
|
||||
6. **Use AskUserQuestion tool for confirmation**: Wait for explicit approval before proceeding
|
||||
7. **After user confirms**: Delegate to ticket-assistant agent to update ticket
|
||||
8. Report changes applied
|
||||
|
||||
**Guidelines**:
|
||||
- Be specific: quote the problematic text
|
||||
- Explain the "why" behind each suggested change
|
||||
- Distinguish between critical (must fix) and nice-to-have improvements
|
||||
- Use AskUserQuestion tool if context is ambiguous or requires clarification
|
||||
|
||||
### 3. Analyze Tickets for Quality
|
||||
|
||||
**Scenario**: "Review existing Linear tickets for completeness, clarity, dependencies, open questions" for range AIA-100 through AIA-110
|
||||
|
||||
**Process**:
|
||||
1. Delegate to ticket-assistant agent to fetch tickets in range
|
||||
2. For each ticket, evaluate against criteria:
|
||||
- **Clarity**: Title, description, acceptance criteria
|
||||
- **Completeness**: All required fields, edge cases covered
|
||||
- **Dependencies**: Blocks/Blocked-by relationships identified
|
||||
- **Open questions**: Uncertainties flagged
|
||||
3. Use `references/analysis_patterns.md` Pattern 4 for systematic evaluation
|
||||
4. Compile findings:
|
||||
- Strong tickets (ready for development)
|
||||
- Needs work (specific improvements recommended)
|
||||
- Needs breakdown (too large)
|
||||
- Blocked (waiting on decisions)
|
||||
5. Present report with:
|
||||
- Summary per ticket
|
||||
- Recommended actions
|
||||
- Highest-priority refinements needed
|
||||
|
||||
**Guidelines**:
|
||||
- Use consistent evaluation structure
|
||||
- Highlight both strengths and issues
|
||||
- Provide specific, actionable recommendations
|
||||
- Flag patterns across multiple tickets (e.g., all missing error handling)
|
||||
|
||||
### 4. Identify Gaps in Epic Coverage
|
||||
|
||||
**Scenario**: "Identify gaps in the planned tickets for epic XXX-123"
|
||||
|
||||
**Process**:
|
||||
1. Delegate to ticket-assistant agent to fetch epic and sub-tickets
|
||||
2. Analyze epic scope vs. ticket coverage using `references/analysis_patterns.md` Pattern 1:
|
||||
- Frontend/UI components
|
||||
- Backend services and APIs
|
||||
- Testing and QA work
|
||||
- Documentation and knowledge base
|
||||
- Deployment or infrastructure
|
||||
- Edge cases and error scenarios
|
||||
3. Present findings:
|
||||
- Identified gaps with context
|
||||
- Suggested new tickets for each gap
|
||||
- Estimated scope per gap
|
||||
4. **Use AskUserQuestion tool for confirmation**: Present options to create all tickets, select specific ones, or review proposals first
|
||||
5. **After user confirms**: Delegate to ticket-assistant agent to create tickets
|
||||
|
||||
**Guidelines**:
|
||||
- Be thorough but realistic (not everything needs a separate ticket)
|
||||
- Group related gaps (e.g., multiple API endpoints in one ticket)
|
||||
- Consider team's estimation approach when scoping gaps
|
||||
- Link new tickets to epic as subtickets
|
||||
|
||||
### 5. Analyze Dependencies and Suggest Parallelization
|
||||
|
||||
**Scenario**: User asks about dependencies between tickets or how to parallelize work
|
||||
|
||||
**Process**:
|
||||
1. Delegate to ticket-assistant agent to fetch relevant tickets
|
||||
2. Use `references/analysis_patterns.md` Pattern 3:
|
||||
- Extract explicit Blocks/Blocked-by relationships
|
||||
- Identify implicit dependencies
|
||||
- Find critical path (work that must complete first)
|
||||
- Group by parallelizable tracks
|
||||
3. Present parallelization strategy:
|
||||
- Work that can happen simultaneously
|
||||
- Critical path dependencies
|
||||
- Recommended team allocation
|
||||
4. Suggest implementation sequence
|
||||
|
||||
**Guidelines**:
|
||||
- Consider frontend/backend can often run in parallel if API contract is clear
|
||||
- Testing can often run alongside implementation if setup is clear
|
||||
- Documentation can start early with skeleton/outline
|
||||
- Infrastructure work often critical path
|
||||
|
||||
### 6. Generate Refinement Session Questions
|
||||
|
||||
**Scenario**: "Generate questions for the next refinement session for tickets XXX-100 through XXX-110"
|
||||
|
||||
**Process**:
|
||||
1. Delegate to ticket-assistant agent to fetch ticket range
|
||||
2. Analyze each ticket for uncertainty patterns:
|
||||
- Missing acceptance criteria
|
||||
- Ambiguous requirements
|
||||
- Unknown trade-offs
|
||||
- Implicit assumptions
|
||||
- Unclear edge cases
|
||||
3. Use `references/refinement_session_guide.md` and `references/analysis_patterns.md` Pattern 5
|
||||
4. Generate questions organized by:
|
||||
- **Critical blockers**: Must resolve first
|
||||
- **Design/Technical questions**: Needed before building
|
||||
- **Edge cases**: Clarify completeness
|
||||
- **Dependencies**: Identify coordination needs
|
||||
- **Success metrics**: Define what "done" means
|
||||
5. Present as structured question set with:
|
||||
- Target audience (Product, Engineering, Design)
|
||||
- Why the question matters
|
||||
- Suggested answers or options
|
||||
|
||||
**Guidelines**:
|
||||
- Prioritize high-impact questions first
|
||||
- Frame as open-ended (not leading)
|
||||
- Group related questions by theme
|
||||
- Note interdependencies between questions
|
||||
- Suggest time-boxing for discussion
|
||||
|
||||
## Reference Materials
|
||||
|
||||
### Ticket Structure and Templates
|
||||
- **`references/ticket_structure_guide.md`** - Title guidelines, label categories, description formats, acceptance criteria best practices, refinement checklist, red flags
|
||||
- **`assets/ticket_template.md`** - Ready-to-use templates for simple/complex/bug/epic tickets
|
||||
|
||||
### Analysis Patterns
|
||||
- **`references/analysis_patterns.md`** - 6 structured reasoning patterns:
|
||||
1. Identifying gaps in epic coverage
|
||||
2. Detecting assumption mismatches
|
||||
3. Dependency analysis and parallelization
|
||||
4. Clarity and completeness review
|
||||
5. Generating refinement session questions
|
||||
6. Epic analysis and adjustment suggestions
|
||||
|
||||
### Refinement Sessions
|
||||
- **`references/refinement_session_guide.md`** - Question generation strategies, facilitation tips, sample agendas, post-refinement checklist
|
||||
|
||||
### When to Use Each Analysis Pattern
|
||||
|
||||
| Pattern | Trigger Question | Reference |
|
||||
|---------|------------------|-----------|
|
||||
| Gap Identification | "Identify gaps in epic XXX" | `analysis_patterns.md` Pattern 1 |
|
||||
| Assumption Mismatch | "Are there wrong assumptions?" | `analysis_patterns.md` Pattern 2 |
|
||||
| Dependency Analysis | "What are dependencies?" | `analysis_patterns.md` Pattern 3 |
|
||||
| Quality Review | "Review tickets for completeness" | `analysis_patterns.md` Pattern 4 |
|
||||
| Refinement Questions | "Generate questions for session" | `analysis_patterns.md` Pattern 5, `refinement_session_guide.md` |
|
||||
| Epic Adjustment | "Suggest adjustments to epic" | `analysis_patterns.md` Pattern 6 |
|
||||
|
||||
## Workflow: Create and Propose
|
||||
|
||||
All creation and amendment operations follow this pattern:
|
||||
|
||||
### Step 1: Gather Context
|
||||
- User provides requirements (conversation, transcript, existing ticket)
|
||||
- If ticket data is needed, delegate to ticket-assistant agent
|
||||
|
||||
### Step 2: Analyze and Draft
|
||||
- Use appropriate patterns from `references/analysis_patterns.md`
|
||||
- Follow structure from `references/ticket_structure_guide.md` or templates
|
||||
- Draft ticket/amendment with complete context
|
||||
|
||||
### Step 3: Present for Review
|
||||
- Show "current state" and "proposed state" for amendments
|
||||
- Show "proposed ticket" for new tickets
|
||||
- Include rationale for each decision
|
||||
- Use AskUserQuestion tool if clarification is needed
|
||||
|
||||
### Step 4: Wait for Confirmation
|
||||
- **Use AskUserQuestion tool** to get explicit user confirmation before proceeding
|
||||
- **Do not proceed** until user confirms via the tool response
|
||||
- Offer to adjust draft if user suggests changes
|
||||
- Re-present adjusted version and confirm again using AskUserQuestion
|
||||
|
||||
### Step 5: Apply Changes
|
||||
- Delegate to ticket-assistant agent to create/update tickets
|
||||
- Agent handles all PM system-specific operations
|
||||
|
||||
### Step 6: Report Results
|
||||
- Confirm what was created/updated
|
||||
- Provide ticket ID and Link (if available)
|
||||
- Ask: "What would you like to do next?"
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Ticket Quality
|
||||
- Read `references/ticket_structure_guide.md` for quality standards
|
||||
- Ensure titles are specific and action-oriented
|
||||
- Include acceptance criteria for complex work
|
||||
- Flag open questions when scope is unclear
|
||||
- Link dependencies explicitly
|
||||
|
||||
### Analysis Completeness
|
||||
- Quote specific text when identifying issues
|
||||
- Explain the "why" behind recommendations
|
||||
- Distinguish between facts (what's written) and inferences
|
||||
- Flag assumptions clearly
|
||||
- Suggest options with trade-offs when multiple paths exist
|
||||
|
||||
### User Confirmation Protocol
|
||||
- Always show proposals before applying
|
||||
- **Use AskUserQuestion tool** to get explicit user confirmation with clear options
|
||||
- Wait for confirmation response from the tool before proceeding
|
||||
- Never assume approval
|
||||
- Offer revision if user suggests changes
|
||||
- Re-present for approval after revisions (using AskUserQuestion again)
|
||||
|
||||
### Delegating to Agent
|
||||
- Use ticket-assistant agent for all data operations (get, list, create, update, search)
|
||||
- Agent handles PM system detection and operations
|
||||
- Focus skill logic on analysis, shaping, and best practices
|
||||
|
||||
## Using AskUserQuestion for User Input
|
||||
|
||||
When user input is required during workflow execution, use the **AskUserQuestion** tool to present structured options. This ensures clear, actionable choices and reduces ambiguity.
|
||||
|
||||
### When to Use AskUserQuestion
|
||||
|
||||
Use the tool for:
|
||||
1. **Clarifying questions during analysis** - When requirements, scope, or context needs clarification
|
||||
2. **Confirmation before actions** - Before creating or updating tickets in the PM system
|
||||
|
||||
Do NOT use for:
|
||||
- Open-ended conversational follow-ups ("What would you like to do next?")
|
||||
- Refinement session questions (those are for human facilitators)
|
||||
|
||||
### Example 1: Clarifying Requirements During Analysis
|
||||
|
||||
**Scenario**: Analyzing a ticket but scope is ambiguous between two interpretations.
|
||||
|
||||
```
|
||||
Use AskUserQuestion tool with:
|
||||
{
|
||||
"questions": [{
|
||||
"question": "The ticket mentions 'email notifications' but doesn't specify the scope. What should be included?",
|
||||
"header": "Scope",
|
||||
"multiSelect": true,
|
||||
"options": [
|
||||
{
|
||||
"label": "Digest emails",
|
||||
"description": "Scheduled summary emails sent daily/weekly"
|
||||
},
|
||||
{
|
||||
"label": "Real-time notifications",
|
||||
"description": "Immediate emails when events occur"
|
||||
},
|
||||
{
|
||||
"label": "Transactional emails",
|
||||
"description": "System-triggered emails (password reset, confirmations)"
|
||||
}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: Confirming Before Creating Tickets
|
||||
|
||||
**Scenario**: Identified 3 gaps in epic coverage, ready to create tickets.
|
||||
|
||||
```
|
||||
Use AskUserQuestion tool with:
|
||||
{
|
||||
"questions": [{
|
||||
"question": "I've identified 3 missing tickets for the email digest epic. Should I create them?",
|
||||
"header": "Create Tickets",
|
||||
"multiSelect": false,
|
||||
"options": [
|
||||
{
|
||||
"label": "Create all 3 tickets",
|
||||
"description": "Create tickets for: UI preferences component, end-to-end testing, and scheduled job setup"
|
||||
},
|
||||
{
|
||||
"label": "Show me the proposals first",
|
||||
"description": "Present detailed ticket proposals for review before creating"
|
||||
},
|
||||
{
|
||||
"label": "Create only high-priority ones",
|
||||
"description": "Create tickets for UI component and testing, defer infrastructure work"
|
||||
}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### Guidelines for Effective Questions
|
||||
|
||||
**Structure**:
|
||||
- Use clear, specific question text
|
||||
- Provide 2-4 options (not just yes/no when possible)
|
||||
- Include descriptions explaining what each option means
|
||||
- Use `multiSelect: true` only when choices are not mutually exclusive
|
||||
|
||||
**Headers**:
|
||||
- Keep short (max 12 chars): "Scope", "Approach", "Confirm", "Priority"
|
||||
- Describes the decision type
|
||||
|
||||
**Options**:
|
||||
- Label: Concise choice (1-5 words)
|
||||
- Description: Explain implications or what happens if chosen
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
plugins/pm-assistant/skills/ticket-assistant/
|
||||
├── SKILL.md # This file
|
||||
├── README.md # User-facing documentation
|
||||
├── assets/
|
||||
│ └── ticket_template.md # Ticket templates
|
||||
├── references/ # Domain knowledge
|
||||
│ ├── ticket_structure_guide.md # Ticket quality standards
|
||||
│ ├── analysis_patterns.md # Analysis methodologies
|
||||
│ └── refinement_session_guide.md # Refinement facilitation
|
||||
└── connectors/ # PM system reference (optional)
|
||||
└── linear.md # Linear MCP quick reference (if needed)
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Maximum 500 words per ticket (concise content)
|
||||
- All timestamps use ISO 8601 format
|
||||
- Descriptions support Markdown formatting
|
||||
- Always delegate ticket data operations to ticket-assistant agent
|
||||
- Focus on analysis, shaping, and best practices in this skill
|
||||
264
skills/product-manager/assets/ticket_template.md
Normal file
264
skills/product-manager/assets/ticket_template.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# Ticket Template
|
||||
|
||||
Use this template as a starting point for new tickets. Adapt based on complexity:
|
||||
- **Simple tickets**: Use minimal template (title + brief what/why/how)
|
||||
- **Complex features**: Use full template with all sections
|
||||
- **Bugs**: Use bug-specific template (STR + Expected vs Actual)
|
||||
|
||||
## Simple Ticket Template
|
||||
|
||||
```
|
||||
Title: [Action] [What] [Where if specific]
|
||||
|
||||
[1-2 sentence context about why this matters]
|
||||
|
||||
[Brief: what needs to change]
|
||||
|
||||
Acceptance Criteria:
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
```
|
||||
|
||||
## Complex Feature Ticket Template
|
||||
|
||||
```
|
||||
Title: [Action] [What] for [User Type/Context]
|
||||
|
||||
## Context
|
||||
[2-3 sentences explaining why this matters]
|
||||
- Problem it solves:
|
||||
- User impact:
|
||||
- Business value:
|
||||
|
||||
## Requirements
|
||||
- Functional requirement 1
|
||||
- Functional requirement 2
|
||||
- Non-functional requirement (performance, compatibility, etc.)
|
||||
- Integration points with [System X]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Given-When-Then Examples
|
||||
Given [initial state]
|
||||
When [action taken]
|
||||
Then [expected outcome]
|
||||
|
||||
### Additional Checkboxes
|
||||
- [ ] API endpoint returns 200 status
|
||||
- [ ] Error handling for [edge case] returns 400
|
||||
- [ ] Documentation updated
|
||||
- [ ] Test coverage at [X]%
|
||||
|
||||
## Open Questions
|
||||
- [Engineering] How should we handle [technical concern]?
|
||||
- [Product] What's the expected behavior for [scenario]?
|
||||
- [Business] Do we need [compliance/security feature]?
|
||||
|
||||
## Dependencies
|
||||
- Depends on: [Ticket ID if applicable]
|
||||
- Blocks: [Ticket ID if applicable]
|
||||
|
||||
## Estimate
|
||||
[Story points or T-shirt size if using estimation]
|
||||
```
|
||||
|
||||
## Bug Ticket Template
|
||||
|
||||
```
|
||||
Title: [Bug] [Component] [Symptom]
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Navigate to [page/screen]
|
||||
2. [Action 1]
|
||||
3. [Action 2]
|
||||
4. [Observe result]
|
||||
|
||||
## Expected Behavior
|
||||
[What should happen]
|
||||
|
||||
## Actual Behavior
|
||||
[What is actually happening]
|
||||
|
||||
## Environment
|
||||
- Browser: [Chrome 120 on macOS / etc.]
|
||||
- Device: [Device model]
|
||||
- OS: [OS and version]
|
||||
- Network: [Stable / Flaky / etc.]
|
||||
- User Type: [Admin / Regular user / etc.]
|
||||
|
||||
## Additional Context
|
||||
[Screenshots, error logs, data samples if helpful]
|
||||
|
||||
## Severity
|
||||
- [ ] Critical (Service down, data loss, security)
|
||||
- [ ] High (Core feature broken, widespread impact)
|
||||
- [ ] Medium (Feature partially broken, workaround exists)
|
||||
- [ ] Low (Minor UI issue, edge case, cosmetic)
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Bug reproduction confirmed
|
||||
- [ ] Root cause identified and documented
|
||||
- [ ] Fix implemented and tested
|
||||
- [ ] Regression test added
|
||||
- [ ] Verified in [environment]
|
||||
```
|
||||
|
||||
## Epic Ticket Template
|
||||
|
||||
```
|
||||
Title: [Capability] for [User/Team/Domain]
|
||||
|
||||
## Overview
|
||||
[1-2 sentence description of the epic scope]
|
||||
|
||||
## Goals
|
||||
- Goal 1: [Specific, measurable outcome]
|
||||
- Goal 2: [Specific, measurable outcome]
|
||||
|
||||
## Scope
|
||||
**In Scope**:
|
||||
- Feature/capability 1
|
||||
- Integration with [System X]
|
||||
- Support for [User type/scenario]
|
||||
|
||||
**Out of Scope** (explicitly defer):
|
||||
- Feature that's related but separate
|
||||
- Advanced feature deferred to later
|
||||
|
||||
## Success Metrics
|
||||
- [Metric 1]: Target [X] by [Date]
|
||||
- [Metric 2]: Target [X] by [Date]
|
||||
|
||||
## Key Dependencies
|
||||
- Requires: [System/Feature that must be in place]
|
||||
- Blocks: [Work that will be blocked on this]
|
||||
- Integrates with: [Related systems]
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] All child tickets completed
|
||||
- [ ] Documentation complete
|
||||
- [ ] [User type] can [primary use case]
|
||||
- [ ] Performance target [X] met
|
||||
- [ ] Rollout to [X]% of users successful
|
||||
|
||||
## Open Questions
|
||||
- [Product] Should we support [feature variant]?
|
||||
- [Engineering] Is [architecture choice] the right approach?
|
||||
- [Design] What's the rollout experience?
|
||||
|
||||
## Planned Breakdown (Initial)
|
||||
- [Ticket category 1]: e.g., Backend API implementation
|
||||
- [Ticket category 2]: e.g., Frontend UI
|
||||
- [Ticket category 3]: e.g., Testing and validation
|
||||
- [Ticket category 4]: e.g., Documentation
|
||||
```
|
||||
|
||||
## Notes on Template Usage
|
||||
|
||||
**Title Writing Tips**:
|
||||
- ✅ "Add CSV export for user data"
|
||||
- ✅ "[Bug] Email parser fails on UTF-8 domains"
|
||||
- ✅ "[Epic] Mobile app for iOS"
|
||||
- ❌ "Export feature"
|
||||
- ❌ "Parser issue"
|
||||
|
||||
**When to use Complex Template**:
|
||||
- Feature impacts multiple systems
|
||||
- Epic or large feature
|
||||
- Cross-team dependencies
|
||||
- Performance or security considerations
|
||||
- Unclear requirements or assumptions
|
||||
|
||||
**When to use Simple Template**:
|
||||
- UI/text changes
|
||||
- Small bug fixes
|
||||
- Documentation updates
|
||||
- Isolated improvements
|
||||
|
||||
**Accepting Criteria Tips**:
|
||||
- Make them testable without ambiguity
|
||||
- Include both happy path and error cases
|
||||
- For complex logic, use Given-When-Then format
|
||||
- For simple features, checkboxes are fine
|
||||
- Avoid "code is clean" or vague criteria
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
**Default: Product-Centric Focus**
|
||||
|
||||
Tickets should prioritize user value and business outcomes:
|
||||
|
||||
✅ **Good - Product-focused**:
|
||||
```
|
||||
Title: Enable users to export their data
|
||||
|
||||
Context:
|
||||
Users need ability to download their data for backup and compliance purposes.
|
||||
This supports GDPR requirements and builds user trust.
|
||||
|
||||
Requirements:
|
||||
- Export button accessible from user profile
|
||||
- Support CSV and JSON formats
|
||||
- Include all user data except internal system fields
|
||||
|
||||
Acceptance Criteria:
|
||||
- [ ] User can initiate export from profile page
|
||||
- [ ] System generates file within 30 seconds
|
||||
- [ ] Downloaded file contains complete user data
|
||||
- [ ] Format selection (CSV/JSON) works correctly
|
||||
```
|
||||
|
||||
❌ **Poor - Too implementation-heavy**:
|
||||
```
|
||||
Title: Add CSV export endpoint
|
||||
|
||||
Context:
|
||||
Need to implement CSV export using fast-csv library.
|
||||
Code: const csv = require('fast-csv'); function exportData() { ... }
|
||||
|
||||
Requirements:
|
||||
- Create /api/export endpoint
|
||||
- Use fast-csv for generation
|
||||
- Return response with proper headers
|
||||
```
|
||||
|
||||
**Including Technical Details**
|
||||
|
||||
Include technical specifics when:
|
||||
|
||||
1. **Explicitly requested**:
|
||||
```
|
||||
User: "Create ticket for payment processing. Make sure to note we're using Stripe, not our usual PayPal."
|
||||
|
||||
✅ Ticket includes:
|
||||
Technical Note: Use Stripe payment gateway (deviation from standard PayPal integration)
|
||||
due to better support for recurring subscriptions.
|
||||
```
|
||||
|
||||
2. **Convention deviation**:
|
||||
```
|
||||
User: "We need to use Redis for this caching layer instead of Memcached"
|
||||
|
||||
✅ Ticket includes:
|
||||
Technical Note: Implement caching with Redis (deviation from Memcached standard)
|
||||
to support pub/sub for real-time invalidation.
|
||||
```
|
||||
|
||||
3. **Critical architectural constraint**:
|
||||
```
|
||||
✅ Ticket includes:
|
||||
Technical Constraint: Use event-driven architecture with message queue
|
||||
to support asynchronous processing and avoid blocking user requests.
|
||||
```
|
||||
|
||||
**What NOT to include**:
|
||||
|
||||
❌ Avoid:
|
||||
- Code snippets or function implementations
|
||||
- Specific variable names or method signatures
|
||||
- Sample code from conversations or documentation
|
||||
|
||||
✅ Instead use:
|
||||
- Architectural patterns: "Use Observer pattern for notifications"
|
||||
- Technology choices: "Implement with WebSockets for bidirectional communication"
|
||||
- Design constraints: "Must support horizontal scaling"
|
||||
359
skills/product-manager/references/analysis_patterns.md
Normal file
359
skills/product-manager/references/analysis_patterns.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# Ticket and Epic Analysis Patterns
|
||||
|
||||
This guide provides structured approaches for analyzing tickets and epics using LLM reasoning.
|
||||
|
||||
## Overview
|
||||
|
||||
Analysis tasks leverage LLM reasoning to:
|
||||
- Identify gaps and missing tickets
|
||||
- Detect mismatches between ticket assumptions and code reality
|
||||
- Find dependencies and relationships
|
||||
- Evaluate ticket clarity and completeness
|
||||
- Generate thoughtful refinement questions
|
||||
|
||||
## Pattern 1: Identifying Gaps in Epic Coverage
|
||||
|
||||
**Scenario**: User wants to identify missing tickets for an epic (e.g., "Identify gaps in epic XXX-123").
|
||||
|
||||
### Process
|
||||
|
||||
1. **Fetch the epic**:
|
||||
- Get the epic issue to understand scope, description, acceptance criteria
|
||||
- Parse the epic's stated goals and requirements
|
||||
|
||||
2. **Fetch all subtickets**:
|
||||
- Query: `parent:"EPIC-ID"`
|
||||
- List all child tickets
|
||||
- Map coverage: which parts of the epic have tickets?
|
||||
|
||||
3. **Analyze coverage**:
|
||||
- Compare epic description against existing tickets
|
||||
- Identify missing areas:
|
||||
- Frontend/UI components not covered
|
||||
- Backend services or APIs not covered
|
||||
- Testing or QA work not covered
|
||||
- Documentation or knowledge base gaps
|
||||
- Deployment or infrastructure work not covered
|
||||
- Look for edge cases or error scenarios
|
||||
- **Content filtering**:
|
||||
- Extract user needs and business value
|
||||
- Translate code discussions to high-level requirements
|
||||
- Exclude code snippets unless explicitly requested
|
||||
- Include technical details when deviating from conventions
|
||||
|
||||
4. **Present findings**:
|
||||
- List identified gaps with context
|
||||
- Suggest new tickets for uncovered work
|
||||
- Include estimated scope for each gap
|
||||
|
||||
### Example Analysis Structure
|
||||
|
||||
**Epic**: "Implement email digest feature"
|
||||
|
||||
**Current tickets**:
|
||||
- AIA-100: Design email digest schema
|
||||
- AIA-101: Build digest generation API
|
||||
- AIA-102: Create email templates
|
||||
|
||||
**Identified gaps**:
|
||||
- [ ] UI component: Digest frequency preferences (suggested: 2-3 points)
|
||||
- [ ] Testing: End-to-end digest flow with real email delivery
|
||||
- [ ] Documentation: Digest API documentation and examples
|
||||
- [ ] Infrastructure: Set up scheduled job for digest generation (cron/task queue)
|
||||
|
||||
## Pattern 2: Detecting Assumption Mismatches
|
||||
|
||||
**Scenario**: User asks "Are there any wrong assumptions in this ticket?" (often comparing ticket description to actual code implementation).
|
||||
|
||||
### Process
|
||||
|
||||
1. **Extract assumptions from ticket**:
|
||||
- Read ticket description, acceptance criteria, requirements
|
||||
- Identify explicit assumptions:
|
||||
- "API returns JSON array"
|
||||
- "User already authenticated"
|
||||
- "Database table exists with these fields"
|
||||
- Identify implicit assumptions:
|
||||
- "Feature X is already implemented"
|
||||
- "Libraries are available in codebase"
|
||||
- "System can handle concurrent requests"
|
||||
|
||||
2. **Cross-reference with provided context**:
|
||||
- User may provide code snippets, implementation details, or codebase structure
|
||||
- Compare assumptions against actual state
|
||||
- Identify mismatches:
|
||||
- API returns different format
|
||||
- Prerequisites not yet implemented
|
||||
- Different database schema
|
||||
- Performance constraints
|
||||
- Library incompatibilities
|
||||
|
||||
3. **Categorize mismatches**:
|
||||
- **Critical**: Breaks implementation (e.g., "API structure wrong")
|
||||
- **High**: Requires significant rework (e.g., "Missing prerequisite")
|
||||
- **Medium**: Needs clarification or small adjustment
|
||||
- **Low**: Minor edge case or optimization
|
||||
|
||||
4. **Present findings with remediation**:
|
||||
- Flag each mismatch clearly
|
||||
- Explain impact on implementation
|
||||
- Suggest updated acceptance criteria or requirements
|
||||
- Use AskUserQuestion tool to confirm: "Should we update the ticket or is there missing context?"
|
||||
|
||||
### Example Mismatch Detection
|
||||
|
||||
**Ticket assumption**: "Email parser API returns structured fields: { sender, subject, body, attachments }"
|
||||
|
||||
**Code reality**: "Parser returns raw MIME structure; field extraction not yet implemented"
|
||||
|
||||
**Mismatch**: Critical
|
||||
- Ticket describes endpoint as done; actually needs field extraction layer
|
||||
- Acceptance criteria unrealistic for current implementation
|
||||
- **Suggested fix**: Split into (1) MIME parsing, (2) field extraction, (3) API endpoint
|
||||
|
||||
## Pattern 3: Dependency Analysis and Parallelization
|
||||
|
||||
**Scenario**: User wants to understand dependencies across tickets for parallel work.
|
||||
|
||||
### Process
|
||||
|
||||
1. **Extract dependencies from ticket relationships**:
|
||||
- Review Blocks/Blocked-by relationships
|
||||
- Look for implicit dependencies:
|
||||
- "Requires backend API" → ticket mentions API endpoint
|
||||
- "Needs database migration" → schema changes
|
||||
- "Depends on design decision" → tickets waiting on decisions
|
||||
|
||||
2. **Identify critical path**:
|
||||
- Work that must complete before others can start
|
||||
- Usually: design → backend → frontend → testing
|
||||
|
||||
3. **Group by parallelizable tracks**:
|
||||
- Frontend UI work (if API contract defined)
|
||||
- Backend API implementation
|
||||
- Testing and QA scenarios
|
||||
- Documentation and knowledge base
|
||||
- Infrastructure/deployment work
|
||||
|
||||
4. **Suggest optimal sequence**:
|
||||
- Propose which work can happen in parallel
|
||||
- Identify blockers that must resolve first
|
||||
- Recommend team allocation to maximize parallelization
|
||||
|
||||
### Example Parallelization
|
||||
|
||||
**Tickets for feature**: Email digest feature (AIA-100 to AIA-105)
|
||||
|
||||
**Analysis**:
|
||||
- AIA-100 (Design schema) - critical path start
|
||||
- AIA-101 (Backend API) - depends on AIA-100 ✓ can start after design
|
||||
- AIA-102 (Email templates) - independent ✓ can start immediately
|
||||
- AIA-103 (Frontend UI) - depends on AIA-101 API contract
|
||||
- AIA-104 (Testing) - depends on AIA-101 being runnable
|
||||
- AIA-105 (Documentation) - can start after AIA-100
|
||||
|
||||
**Suggested parallelization**:
|
||||
1. **Start simultaneously**: AIA-100 (design), AIA-102 (templates)
|
||||
2. **Once AIA-100 done**: Start AIA-101 (backend), AIA-105 (docs)
|
||||
3. **Once AIA-101 done**: Start AIA-103 (frontend), AIA-104 (testing)
|
||||
|
||||
## Pattern 4: Clarity and Completeness Review
|
||||
|
||||
**Scenario**: User asks "Review existing Linear tickets for completeness, clarity, dependencies, open questions" for a range of tickets.
|
||||
|
||||
### Process
|
||||
|
||||
1. **Fetch all tickets** in the specified range (e.g., AIA-100 through AIA-110)
|
||||
|
||||
2. **Evaluate each ticket against criteria**:
|
||||
|
||||
**Clarity Assessment**:
|
||||
- Is title specific and action-oriented?
|
||||
- Is description concise and understandable?
|
||||
- Are acceptance criteria testable and specific?
|
||||
- Would a developer confidently estimate and implement?
|
||||
|
||||
**Completeness Check**:
|
||||
- Does complex ticket have acceptance criteria?
|
||||
- Are bugs reproducible (steps provided)?
|
||||
- Are features properly scoped?
|
||||
- Are dependencies identified?
|
||||
- Are open questions flagged?
|
||||
|
||||
**Dependency Verification**:
|
||||
- Are blocking relationships explicitly set?
|
||||
- Could work run in parallel if clearer?
|
||||
- Are implicit dependencies made explicit?
|
||||
|
||||
**Open Questions Assessment**:
|
||||
- Are uncertainties flagged?
|
||||
- Are questions assignable to right parties?
|
||||
|
||||
3. **Compile findings**:
|
||||
- Create summary per ticket
|
||||
- Highlight strengths and issues
|
||||
- Rank by urgency of refinement needed
|
||||
|
||||
4. **Present with recommendations**:
|
||||
- Strong tickets (ready for development)
|
||||
- Needs clarity (specific improvements recommended)
|
||||
- Needs breakdown (too large or complex)
|
||||
- Blocked by decisions (needs input from product/design)
|
||||
|
||||
### Evaluation Template
|
||||
|
||||
For each ticket, assess:
|
||||
|
||||
```
|
||||
Ticket: AIA-XXX - [Title]
|
||||
Status: [Ready/Needs Work/Blocked]
|
||||
|
||||
Clarity: [✓/⚠/✗] with reason
|
||||
Completeness: [✓/⚠/✗] with reason
|
||||
Dependencies: [✓/⚠/✗] with reason
|
||||
Questions: [✓/⚠/✗] with reason
|
||||
|
||||
Issues found:
|
||||
- [Issue 1 with recommendation]
|
||||
|
||||
Recommended next step:
|
||||
- [Action needed]
|
||||
```
|
||||
|
||||
## Pattern 5: Generating Refinement Session Questions
|
||||
|
||||
**Scenario**: User asks "Generate questions for the next refinement session for tickets XXX-100 through XXX-110".
|
||||
|
||||
### Process
|
||||
|
||||
1. **Fetch tickets** in the range
|
||||
|
||||
2. **Identify uncertainty patterns**:
|
||||
- Missing acceptance criteria
|
||||
- Ambiguous requirements
|
||||
- Conflicting specs
|
||||
- Implicit assumptions
|
||||
- Unknown edge cases
|
||||
- Unclear priorities or value
|
||||
|
||||
3. **Generate clarifying questions** organized by type:
|
||||
|
||||
**For Product/Business**:
|
||||
- "What's the priority of this feature relative to X?"
|
||||
- "Who is the primary user and what problem does this solve?"
|
||||
- "What's the expected timeline/deadline?"
|
||||
- "Are there any compliance or regulatory requirements?"
|
||||
|
||||
**For Engineering**:
|
||||
- "Is this technically feasible with current stack?"
|
||||
- "Are there performance constraints we should consider?"
|
||||
- "Does this require changes to authentication/authorization?"
|
||||
- "What's the rollout strategy (feature flag, gradual, etc.)?"
|
||||
|
||||
**For Design/UX**:
|
||||
- "Have we designed the user flows for this?"
|
||||
- "Are there accessibility requirements?"
|
||||
- "What's the visual/interaction pattern from existing UI?"
|
||||
|
||||
**For All**:
|
||||
- "How does this integrate with existing feature X?"
|
||||
- "What happens in error scenarios?"
|
||||
- "What's the success metric for this?"
|
||||
|
||||
4. **Organize questions strategically**:
|
||||
- Start with high-impact, blockers
|
||||
- Group by theme or epic
|
||||
- Flag critical unknowns
|
||||
- Note dependencies between questions
|
||||
|
||||
### Example Question Set
|
||||
|
||||
**For epic "Email digest feature" refinement session**:
|
||||
|
||||
**Critical blockers** (must resolve first):
|
||||
- [Product] Is the digest frequency (daily/weekly/monthly) configurable per user or system-wide?
|
||||
- [Engineering] Can our email system handle the volume of digest sends? Should we batch them?
|
||||
|
||||
**Design questions** (needed before building):
|
||||
- [Design] Have we designed the digest preview UI?
|
||||
- [All] What unsubscribe mechanism do we need for digests?
|
||||
|
||||
**Edge cases** (clarify before acceptance):
|
||||
- [Product] What happens if a user has no emails in the digest period?
|
||||
- [Engineering] How do we handle timezone differences for "weekly" digests?
|
||||
|
||||
## Pattern 6: Epic Analysis and Adjustment Suggestions
|
||||
|
||||
**Scenario**: User wants "Based on the conversation transcript suggest adjustments to the epic XXX-123".
|
||||
|
||||
### Process
|
||||
|
||||
1. **Fetch the epic** with full description and current subtickets
|
||||
|
||||
2. **Analyze conversation transcript** for:
|
||||
- New insights or requirements not in epic description
|
||||
- Stakeholder concerns or constraints
|
||||
- Changed priorities or scope
|
||||
- Technical challenges or trade-offs discussed
|
||||
- User feedback or use cases mentioned
|
||||
|
||||
3. **Cross-reference with current epic**:
|
||||
- What's aligned between epic description and conversation?
|
||||
- What's missing from epic description?
|
||||
- What's in epic that wasn't discussed or is outdated?
|
||||
- Are subtickets still appropriate?
|
||||
|
||||
4. **Suggest adjustments**:
|
||||
- Update epic description with new context
|
||||
- Recommend new tickets for discussion outcomes
|
||||
- Suggest removing or deferring scope
|
||||
- Highlight dependencies discovered in discussion
|
||||
- Flag trade-offs for decision
|
||||
|
||||
5. **Present as proposed amendments**:
|
||||
- "Current epic description" vs. "Suggested updates"
|
||||
- "Current subtickets" vs. "Suggested changes"
|
||||
- Rationale for each change
|
||||
|
||||
### Amendment Template
|
||||
|
||||
```
|
||||
Epic: XXX-123 - [Current Title]
|
||||
|
||||
Current scope: [quote from description]
|
||||
|
||||
Suggested scope updates:
|
||||
- Add: [new requirement or insight]
|
||||
- Remove: [scope to defer]
|
||||
- Clarify: [ambiguous part with suggested rewording]
|
||||
|
||||
New subtickets suggested:
|
||||
- [Ticket with estimated scope]
|
||||
|
||||
Subtickets to reconsider:
|
||||
- [Ticket that may no longer fit]
|
||||
|
||||
Dependencies or blockers discovered:
|
||||
- [Dependency or constraint]
|
||||
```
|
||||
|
||||
## General Analysis Guidelines
|
||||
|
||||
**Always**:
|
||||
- Quote specific text from tickets/epics in findings
|
||||
- Provide specific, actionable recommendations
|
||||
- Explain the "why" behind observations
|
||||
- Distinguish between facts (what's written) and inferences (what's implied)
|
||||
- Flag assumptions clearly
|
||||
|
||||
**Consider**:
|
||||
- Team's estimation approach (story points, t-shirt, none)
|
||||
- Sprint velocity and capacity
|
||||
- Current backlog health and priorities
|
||||
- Existing patterns in ticket structure (to match style)
|
||||
|
||||
**When unsure**:
|
||||
- Use AskUserQuestion tool for clarifying questions
|
||||
- Flag as open question for refinement
|
||||
- Suggest options with trade-offs
|
||||
- Don't assume team preferences or standards
|
||||
333
skills/product-manager/references/refinement_session_guide.md
Normal file
333
skills/product-manager/references/refinement_session_guide.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# Refinement Session Guide
|
||||
|
||||
This guide explains how to prepare for and facilitate refinement sessions, including generating meaningful discussion questions.
|
||||
|
||||
## Refinement Session Overview
|
||||
|
||||
Refinement sessions are where product teams:
|
||||
- Discuss upcoming work (next 2-3 sprints)
|
||||
- Break down epics into actionable tickets
|
||||
- Clarify requirements and acceptance criteria
|
||||
- Identify dependencies and blockers
|
||||
- Estimate complexity (if using estimation)
|
||||
- Align on priorities
|
||||
|
||||
## Pre-Refinement: Generating Questions
|
||||
|
||||
**Scenario**: "Generate questions for the next refinement session for tickets XXX-100 through XXX-110"
|
||||
|
||||
### Question Generation Strategy
|
||||
|
||||
Generate questions that:
|
||||
1. **Unblock implementation** - Remove technical uncertainties
|
||||
2. **Clarify value** - Ensure everyone understands the "why"
|
||||
3. **Surface dependencies** - Identify work that affects other work
|
||||
4. **Challenge assumptions** - Find gaps in thinking
|
||||
5. **Enable estimation** - Provide clarity for sizing complexity
|
||||
|
||||
### Question Categories and Examples
|
||||
|
||||
#### 1. Scope and Value Questions
|
||||
|
||||
**Product/Business focus**:
|
||||
- "What's the primary user need this solves?"
|
||||
- "Why now? What drives the priority?"
|
||||
- "How does this relate to our OKRs?"
|
||||
- "What's the definition of success?"
|
||||
- "Who should we talk to validate this with users?"
|
||||
|
||||
**When to use**: For new features, roadmap items, or items with unclear "why"
|
||||
|
||||
#### 2. Technical Feasibility Questions
|
||||
|
||||
**Engineering focus**:
|
||||
- "Is our current tech stack a good fit for this?"
|
||||
- "Are there performance or scalability concerns?"
|
||||
- "Do we need new infrastructure or tooling?"
|
||||
- "Is this technically feasible in the next sprint?"
|
||||
- "What technical debt might block this?"
|
||||
|
||||
**When to use**: Complex features, infrastructure work, new integrations
|
||||
|
||||
#### 3. Design and UX Questions
|
||||
|
||||
**Design focus**:
|
||||
- "Have we designed this user flow?"
|
||||
- "Are there accessibility requirements?"
|
||||
- "How does this fit our existing design system?"
|
||||
- "What's the mobile experience like?"
|
||||
- "Should we prototype or validate first?"
|
||||
|
||||
**When to use**: Customer-facing features, UI changes
|
||||
|
||||
#### 4. Dependency and Integration Questions
|
||||
|
||||
**Cross-functional**:
|
||||
- "Does this depend on other work in progress?"
|
||||
- "Could this block other teams or projects?"
|
||||
- "Does this integrate with [system X]? How?"
|
||||
- "What APIs or data do we need from [team Y]?"
|
||||
- "What's the integration test strategy?"
|
||||
|
||||
**When to use**: Any feature involving multiple systems, teams, or components
|
||||
|
||||
#### 5. Edge Cases and Error Handling
|
||||
|
||||
**Completeness focus**:
|
||||
- "What happens if [error scenario]?"
|
||||
- "How do we handle concurrent requests?"
|
||||
- "What's the rollback strategy if things go wrong?"
|
||||
- "Are there rate limits or capacity considerations?"
|
||||
- "What about inactive/deleted users/data?"
|
||||
|
||||
**When to use**: Critical systems, features affecting data integrity, payment/security
|
||||
|
||||
#### 6. Decision-Required Questions
|
||||
|
||||
**Flag blockers**:
|
||||
- "Do we need a design decision before starting?"
|
||||
- "Should we do [approach A] or [approach B]? What are the trade-offs?"
|
||||
- "Is this a platform-wide change requiring architectural decision?"
|
||||
- "Should we spike this first to reduce uncertainty?"
|
||||
|
||||
**When to use**: Items with multiple paths forward or architectural implications
|
||||
|
||||
#### 7. Rollout and Deployment Questions
|
||||
|
||||
**Operations focus**:
|
||||
- "Should this go behind a feature flag?"
|
||||
- "How do we roll this out without impacting users?"
|
||||
- "What monitoring/alerts do we need?"
|
||||
- "Is there a canary/gradual rollout strategy?"
|
||||
- "What's the rollback procedure?"
|
||||
|
||||
**When to use**: User-facing changes, infrastructure changes, high-impact work
|
||||
|
||||
### Question Framing for Different Audiences
|
||||
|
||||
**For Engineering-heavy sessions**:
|
||||
- Focus on technical feasibility and dependencies
|
||||
- Include spike/investigation questions
|
||||
- Address edge cases and error scenarios
|
||||
- Discuss performance and testing implications
|
||||
|
||||
**For Product-heavy sessions**:
|
||||
- Emphasize user value and success metrics
|
||||
- Clarify scope and priorities
|
||||
- Discuss trade-offs between features
|
||||
- Identify missing user research or validation
|
||||
|
||||
**For Cross-functional sessions**:
|
||||
- Start with "why" (value and goals)
|
||||
- Surface dependencies early
|
||||
- Identify design/technical gaps
|
||||
- End with "what's next" (work plan)
|
||||
|
||||
## Sample Refinement Question Sets
|
||||
|
||||
### Example 1: New Feature (Email Digest)
|
||||
|
||||
```
|
||||
**Value & Scope**:
|
||||
- What problem does email digest solve for users?
|
||||
- Who's the primary user? What's their current workflow?
|
||||
- Should frequency be configurable per user or system-wide?
|
||||
|
||||
**Technical**:
|
||||
- Can our email system handle batch sending this volume?
|
||||
- Should we use a background job or scheduled task?
|
||||
- What email format (HTML/plain text/both)?
|
||||
|
||||
**Edge Cases**:
|
||||
- What if user has no emails in the period?
|
||||
- How do we handle timezone differences?
|
||||
- Unsubscribe mechanism?
|
||||
|
||||
**Dependencies**:
|
||||
- Does this block or depend on other email features?
|
||||
- Do we need design approval before building?
|
||||
|
||||
**Success**:
|
||||
- How do we measure if this succeeds?
|
||||
- What's the rollout timeline?
|
||||
```
|
||||
|
||||
### Example 2: Bug Fix (Parser Failing on Special Characters)
|
||||
|
||||
```
|
||||
**Clarification**:
|
||||
- What's the impact? How many users affected?
|
||||
- Which special characters cause failures?
|
||||
- Is this a security issue or just a UX problem?
|
||||
|
||||
**Root Cause**:
|
||||
- Have we root-caused this?
|
||||
- Is it encoding, parsing, or validation?
|
||||
|
||||
**Solution Scope**:
|
||||
- Should we fix just these characters or handle all UTF-8?
|
||||
- Do we need to update error messages?
|
||||
- Should we add input validation on the frontend?
|
||||
|
||||
**Testing**:
|
||||
- What test cases should we add?
|
||||
- How do we prevent regression?
|
||||
|
||||
**Rollout**:
|
||||
- Is this a hotfix or can we batch with other parser work?
|
||||
- Do we need to handle existing data that's affected?
|
||||
```
|
||||
|
||||
### Example 3: Infrastructure Work (Database Migration)
|
||||
|
||||
```
|
||||
**Why and When**:
|
||||
- Why do we need this migration now?
|
||||
- What's the impact of not doing it?
|
||||
- Is this blocking feature work?
|
||||
|
||||
**Approach**:
|
||||
- What's the migration strategy (zero-downtime? maintenance window?)?
|
||||
- Do we need a feature flag or gradual rollout?
|
||||
- What's the rollback plan?
|
||||
|
||||
**Scope**:
|
||||
- Affected tables and data volumes?
|
||||
- Performance impact?
|
||||
- Monitoring and alerting?
|
||||
|
||||
**Dependencies**:
|
||||
- Deployment sequence with other work?
|
||||
- Do other teams need to prepare?
|
||||
|
||||
**Communication**:
|
||||
- Do users need notification?
|
||||
- What's the customer-facing impact?
|
||||
```
|
||||
|
||||
## During Refinement: Using Questions to Guide Discussion
|
||||
|
||||
### Facilitation Tips
|
||||
|
||||
**Opening** (set context):
|
||||
- "We're refining the next 2 sprints' work"
|
||||
- "Goal is to clarify scope, surface unknowns, and identify dependencies"
|
||||
- "It's okay if we don't have all answers—we'll capture questions for resolution"
|
||||
|
||||
**Present the work** (overview):
|
||||
- Share epic or feature theme
|
||||
- Briefly describe what we're working on
|
||||
- Set the context for why now
|
||||
|
||||
**Ask clarifying questions** (engagement):
|
||||
- Start with scope and value: "What problem does this solve?"
|
||||
- Move to feasibility: "Is this technically doable?"
|
||||
- Explore details: "What about edge case X?"
|
||||
- Flag unknowns: "Do we need design input on this?"
|
||||
|
||||
**Capture decisions** (outcomes):
|
||||
- What did we decide?
|
||||
- What's still open?
|
||||
- Who owns next steps?
|
||||
|
||||
**Identify follow-ups** (action items):
|
||||
- Spike investigations
|
||||
- Design reviews needed
|
||||
- External dependencies
|
||||
- Clarifications from stakeholders
|
||||
|
||||
### Handling "I Don't Know" Responses
|
||||
|
||||
When questions can't be answered:
|
||||
|
||||
1. **Capture as open question**:
|
||||
- Assign to appropriate person/team
|
||||
- Link in ticket for traceability
|
||||
- Flag as blocking or non-blocking
|
||||
|
||||
2. **Offer options to move forward**:
|
||||
- "Should we make an assumption to proceed?"
|
||||
- "Do we need a spike to validate?"
|
||||
- "Can we defer this to a separate ticket?"
|
||||
|
||||
3. **Note dependency**:
|
||||
- "This is blocked on [decision/clarification]"
|
||||
- "Engineering to spike approach by [date]"
|
||||
|
||||
## Post-Refinement: Ticket Quality Checklist
|
||||
|
||||
After refinement, ensure tickets are ready for development:
|
||||
|
||||
### Before Moving to Sprint
|
||||
|
||||
**For each ticket**, verify:
|
||||
|
||||
- [ ] **Title** is specific and action-oriented
|
||||
- [ ] **Description** is concise (150-200 words) and answers: what, why, how
|
||||
- [ ] **Type label** applied (Feature, Bug, Enhancement, etc.)
|
||||
- [ ] **Acceptance criteria** are testable and specific (for complex work)
|
||||
- [ ] **Dependencies** are identified and linked (if applicable)
|
||||
- [ ] **Open questions** are flagged (if any remain)
|
||||
- [ ] **Estimate** is provided (if team uses estimation)
|
||||
- [ ] **No external blockers** (all prerequisites in progress or done)
|
||||
|
||||
### Team Readiness Check
|
||||
|
||||
**Before sprint starts**:
|
||||
- [ ] All near-term tickets are in "Ready for Development" state
|
||||
- [ ] Dependencies between tickets are clear
|
||||
- [ ] Team has asked all blocking questions
|
||||
- [ ] Success metrics defined for features
|
||||
- [ ] Testing approach discussed for new work
|
||||
|
||||
## Sample Refinement Session Agenda
|
||||
|
||||
**Duration**: 60-90 minutes for 2-week sprint
|
||||
|
||||
### Timeboxed Segments
|
||||
|
||||
**0:00-5:00**: Opening and context
|
||||
- Share sprint theme or roadmap context
|
||||
- Overview of items to refine
|
||||
|
||||
**5:00-45:00**: Ticket refinement (30-40 minutes)
|
||||
- Present each epic/feature
|
||||
- Ask clarifying questions
|
||||
- Discuss design, technical approach, edge cases
|
||||
- Identify dependencies
|
||||
- Capture open questions
|
||||
|
||||
**45:00-55:00**: Dependency mapping (10 minutes)
|
||||
- Review identified dependencies
|
||||
- Suggest parallelization opportunities
|
||||
- Flag critical path
|
||||
|
||||
**55:00-85:00**: Estimation and prioritization (20-30 minutes)
|
||||
- If using estimation, estimate tickets
|
||||
- Confirm prioritization
|
||||
- Ensure sprint capacity alignment
|
||||
|
||||
**85:00-90:00**: Wrap-up
|
||||
- Recap decisions and open questions
|
||||
- Assign owners for follow-ups
|
||||
- Confirm next sprint readiness
|
||||
|
||||
## Common Refinement Issues and Solutions
|
||||
|
||||
| Issue | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| "This is too big" | Scope creep or lack of breakdown | Suggest splitting: by layer, by user journey, by value slice |
|
||||
| "We don't know how to estimate" | Missing technical details | Spike first, then estimate. Or use T-shirt sizing (S/M/L). |
|
||||
| "We're blocked on [X]" | External dependency or decision needed | Create separate decision/spike ticket; mark main ticket as blocked |
|
||||
| "Acceptance criteria are too vague" | Product unclear on requirements | Ask specific questions; rewrite criteria to be testable |
|
||||
| "This doesn't fit in a sprint" | Ticket too large | Break into sub-tickets; move lower-priority items to next sprint |
|
||||
| "We forgot about [edge case]" | Incomplete analysis | Add as acceptance criteria; may increase estimate |
|
||||
|
||||
## Tips for Efficient Refinement
|
||||
|
||||
- **Prepare ahead**: Share ticket drafts before the session so team can read
|
||||
- **Time-box discussions**: Allocate time per epic/feature, move on if no progress
|
||||
- **Use templates**: Consistent ticket structure speeds discussion
|
||||
- **Ask not to answer**: Ask questions; don't impose solutions
|
||||
- **Record decisions**: Capture what was decided, not just what was discussed
|
||||
- **Assign ownership**: Each open question has an owner and due date
|
||||
296
skills/product-manager/references/ticket_structure_guide.md
Normal file
296
skills/product-manager/references/ticket_structure_guide.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Ticket Structure and Best Practices
|
||||
|
||||
This guide defines how to structure tickets for clarity, completeness, and actionability.
|
||||
|
||||
## Ticket Content Standards
|
||||
|
||||
**Concise Content**: Maximum 500 words per ticket, ideally 150-200 words.
|
||||
|
||||
## Title Guidelines
|
||||
|
||||
- **Action-oriented**: Start with clear verbs
|
||||
- **Specific**: Include what and where, not just "Fix bug" or "Add feature"
|
||||
- **Under 50 characters**: Concise and scannable
|
||||
- **Examples**:
|
||||
- ✅ "Add CSV export for user data"
|
||||
- ✅ "Fix email parser failing on non-ASCII domains"
|
||||
- ❌ "Export feature"
|
||||
- ❌ "Parser issue"
|
||||
|
||||
## Labels and Categorization
|
||||
|
||||
Always apply type labels for clarity:
|
||||
- `Type/Feature` - New functionality
|
||||
- `Type/Bug` - Defect or broken functionality
|
||||
- `Type/Enhancement` - Improvement to existing feature
|
||||
- `Type/Documentation` - Docs, guides, or knowledge base
|
||||
- `Type/Refactor` - Code cleanup, technical debt
|
||||
- `Type/Testing` - Test coverage improvements
|
||||
- `Type/Infrastructure` - Deployment, CI/CD, DevOps
|
||||
|
||||
Additional context labels from workspace (if available):
|
||||
- Priority labels (if defined): High, Medium, Low
|
||||
- Platform labels: Frontend, Backend, API
|
||||
- Domain labels: specific to team's structure
|
||||
|
||||
## Description Format
|
||||
|
||||
Adapt structure based on ticket complexity:
|
||||
|
||||
### Simple Tickets (UI changes, text updates, small fixes)
|
||||
|
||||
```
|
||||
Brief context (1-2 sentences):
|
||||
- What: What needs to change
|
||||
- Where: Which component/page
|
||||
- Why: Brief reason if not obvious
|
||||
|
||||
Example:
|
||||
The "Save" button label is inconsistent with other forms.
|
||||
|
||||
Change "Save Draft" to "Save" on the user preferences form to match the pattern used across the dashboard.
|
||||
```
|
||||
|
||||
### Complex Tickets (new features, workflows, API changes)
|
||||
|
||||
```
|
||||
## Context
|
||||
Why this matters (2-3 sentences, can quote user feedback):
|
||||
- Problem it solves
|
||||
- User impact
|
||||
- Business value
|
||||
|
||||
## Requirements
|
||||
Specific, detailed needs (bullet points):
|
||||
- Functional requirements
|
||||
- Non-functional requirements (performance, compatibility, etc.)
|
||||
- Integration points
|
||||
|
||||
## Acceptance Criteria
|
||||
Clear, testable conditions. For complex logic, use Given-When-Then format:
|
||||
|
||||
### Given-When-Then Examples:
|
||||
Given a user is on the email settings page
|
||||
When they select "Weekly digest"
|
||||
Then the system saves the preference and shows a confirmation message
|
||||
|
||||
### Simple Checkboxes:
|
||||
- [ ] API endpoint returns 200 status
|
||||
- [ ] Response includes all required fields
|
||||
- [ ] Error handling returns 400 for invalid input
|
||||
|
||||
## Open Questions
|
||||
Flag unknowns for relevant parties (Engineering, Product, Business):
|
||||
- [Engineering] How should we handle authentication for this API?
|
||||
- [Product] What's the expected behavior for returning users?
|
||||
- [Business] Do we need audit logging for compliance?
|
||||
```
|
||||
|
||||
### Bug Tickets
|
||||
|
||||
Include reproducibility information:
|
||||
|
||||
```
|
||||
## Steps to Reproduce
|
||||
1. Navigate to email settings
|
||||
2. Select a date range with special characters
|
||||
3. Click "Apply"
|
||||
|
||||
## Expected Behavior
|
||||
Settings are saved and confirmed with a message
|
||||
|
||||
## Actual Behavior
|
||||
Page throws a 500 error
|
||||
|
||||
## Environment
|
||||
- Browser: Chrome 120 on macOS
|
||||
- Device: MacBook Pro
|
||||
- OS: macOS 14.1
|
||||
- Network: Stable broadband
|
||||
|
||||
## Severity
|
||||
- Critical: Service down, data loss, security issue
|
||||
- High: Core feature broken, widespread impact
|
||||
- Medium: Feature partially broken, workaround exists
|
||||
- Low: Minor UI issue, edge case, cosmetic
|
||||
```
|
||||
|
||||
## Features vs Bugs
|
||||
|
||||
- **Features**: Focus on user need and business value
|
||||
- Why does the user need this?
|
||||
- What problem does it solve?
|
||||
- How does it fit the product roadmap?
|
||||
|
||||
- **Bugs**: Focus on reproduction and impact
|
||||
- Steps to reproduce (numbered, specific)
|
||||
- Expected vs. actual behavior
|
||||
- Environment details
|
||||
- Severity and workarounds
|
||||
|
||||
**Prioritization**: Treat high-severity bugs like features; defer low-severity bugs.
|
||||
|
||||
## Acceptance Criteria Best Practices
|
||||
|
||||
Make acceptance criteria:
|
||||
- **Testable**: Can QA or user verify without ambiguity?
|
||||
- **Specific**: Includes expected data, responses, formats
|
||||
- **Complete**: Covers happy path and error cases
|
||||
- **Independent**: Each criterion can be verified separately
|
||||
|
||||
### Example: Good vs. Poor
|
||||
|
||||
❌ **Poor**: "User can export data"
|
||||
- Too vague. Export to what format? All data or filtered? Where does the file go?
|
||||
|
||||
✅ **Good**:
|
||||
- [ ] Export button appears in the toolbar
|
||||
- [ ] Clicking export shows format options (CSV, Excel, JSON)
|
||||
- [ ] Selected format exports all visible rows
|
||||
- [ ] File downloads to default downloads folder
|
||||
- [ ] Exported file contains all columns shown in current view
|
||||
- [ ] Error handling: Shows message if no data available
|
||||
|
||||
## Dependency Management
|
||||
|
||||
Explicitly capture ticket relationships:
|
||||
|
||||
- **Blocks**: This ticket prevents work on another
|
||||
- Use when: "Backend API must be complete before frontend can integrate"
|
||||
- Example: Create endpoint (blocks) → Integrate in UI
|
||||
|
||||
- **Blocked By**: This ticket is waiting on another
|
||||
- Use when: "Frontend work waiting on API design decision"
|
||||
- Example: Integrate API (blocked by) → API design decision
|
||||
|
||||
- **Relates To**: Related work that should be coordinated but doesn't block
|
||||
- Example: Email parser improvements (relates to) → Email formatting standards
|
||||
|
||||
## Estimation Guidelines
|
||||
|
||||
If team uses estimation:
|
||||
|
||||
- **Story points**: Represent relative complexity, not hours
|
||||
- 1 point: Simple (UI label, small config)
|
||||
- 2-3 points: Straightforward (small feature, isolated fix)
|
||||
- 5-8 points: Moderate (feature with dependencies, multiple components)
|
||||
- 13+ points: Large (complex feature, needs breakdown)
|
||||
|
||||
- **When to split**: Tickets larger than team's typical sprint velocity
|
||||
- Examples: 13+ points should usually be split
|
||||
|
||||
## Ticket Lifecycle States
|
||||
|
||||
Common workflow (adapt to team's actual states):
|
||||
|
||||
1. **Backlog**: New, not yet reviewed
|
||||
2. **Ready for Development**: Refined, detailed, dependencies clear
|
||||
3. **In Progress**: Work started
|
||||
4. **In Review**: Awaiting code/product review
|
||||
5. **Done**: Complete and merged
|
||||
|
||||
## Refinement Checklist
|
||||
|
||||
Before marking ticket as "Ready for Development":
|
||||
|
||||
- [ ] Clear, action-oriented title?
|
||||
- [ ] Description concise and actionable for developers?
|
||||
- [ ] Appropriate labels applied?
|
||||
- [ ] Dependencies identified and linked?
|
||||
- [ ] Acceptance criteria present (for complex work)?
|
||||
- [ ] Open questions flagged for relevant parties?
|
||||
- [ ] Estimate provided (if team uses estimation)?
|
||||
- [ ] No external blockers?
|
||||
|
||||
## Red Flags That Indicate Issues
|
||||
|
||||
During review, flag these as needing refinement:
|
||||
|
||||
- ❌ Tickets older than 90 days without updates
|
||||
- ❌ Missing acceptance criteria on complex tickets
|
||||
- ❌ No clear user value or "why"
|
||||
- ❌ Acceptance criteria that can't be tested
|
||||
- ❌ Unclear dependencies or relationships
|
||||
- ❌ Multiple conflicting acceptance criteria
|
||||
- ❌ Epic stories with no breakdown
|
||||
- ❌ Missing error handling or edge cases
|
||||
|
||||
## Healthy Backlog Indicators
|
||||
|
||||
- Near-term items (next 2 sprints) are detailed and ready
|
||||
- Long-term items (3+ months) are high-level and strategic
|
||||
- Dependencies are mapped and clear
|
||||
- Priorities are current and actionable
|
||||
- Open questions are flagged for resolution
|
||||
- No zombie tickets (unchanged for 6+ months)
|
||||
- Clear epic-to-ticket hierarchy
|
||||
|
||||
## Technical Content Guidelines
|
||||
|
||||
**Default: Product-Centric Focus**
|
||||
|
||||
Tickets should focus on:
|
||||
- User needs and business value
|
||||
- Expected behavior and outcomes
|
||||
- High-level architectural approach (patterns, technology choices)
|
||||
- What needs to happen, not how it will be coded
|
||||
- **NO code snippets or implementation details**
|
||||
|
||||
**Include Technical Details When:**
|
||||
|
||||
1. **Explicitly instructed**: User says "include X" or "make sure to note Y"
|
||||
2. **Convention deviation**: Approach differs from team's standard patterns
|
||||
3. **Critical constraints**: Technical limitations that affect implementation
|
||||
4. **Non-standard technology**: Using different tools/libraries than usual
|
||||
|
||||
**Examples:**
|
||||
|
||||
**Default case:**
|
||||
```
|
||||
User request: "Create a ticket for user authentication"
|
||||
|
||||
✅ Good ticket:
|
||||
Title: Implement user authentication
|
||||
Context: Users need secure authentication to protect their accounts
|
||||
Requirements:
|
||||
- Secure session management
|
||||
- Password reset capability
|
||||
- Multi-factor authentication support
|
||||
|
||||
❌ Poor ticket (too implementation-heavy):
|
||||
Title: Add JWT authentication
|
||||
Context: Need to implement JWT with passport.js library
|
||||
Code: const jwt = require('jsonwebtoken')...
|
||||
```
|
||||
|
||||
**Explicit instruction:**
|
||||
```
|
||||
User request: "Create a ticket for auth, note we're using OAuth2 not JWT"
|
||||
|
||||
✅ Good ticket:
|
||||
Title: Implement OAuth2 authentication
|
||||
Context: Users need secure authentication to protect their accounts
|
||||
Technical Note: Use OAuth2 instead of standard JWT pattern due to third-party integration requirements
|
||||
```
|
||||
|
||||
**Convention deviation:**
|
||||
```
|
||||
User request: "We need to use MongoDB for this feature because of the dynamic schema requirements"
|
||||
|
||||
✅ Good ticket:
|
||||
Title: Implement user preferences storage
|
||||
Context: Users need ability to store custom preferences with flexible structure
|
||||
Technical Note: Use MongoDB for storage (deviation from PostgreSQL standard) due to schema flexibility requirements for custom fields
|
||||
```
|
||||
|
||||
**When to exclude code:**
|
||||
|
||||
❌ Don't include:
|
||||
- Actual code snippets: `function authenticate(user) { ... }`
|
||||
- Specific implementations: variable names, exact method signatures
|
||||
- Example code from discussions
|
||||
|
||||
✅ Instead translate to:
|
||||
- Architectural guidance: "Use Factory pattern for user creation"
|
||||
- Technology choices: "Implement with WebSockets for real-time updates"
|
||||
- Design constraints: "Must be stateless to support horizontal scaling"
|
||||
Reference in New Issue
Block a user