Initial commit

skills/product-manager/references/analysis_patterns.md

@@ -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