Add Technical Writer agent and enhance GitHub integration

.claude/agents/product-manager-advisor.md

@@ -21,7 +21,7 @@ No feature without clear user need. No GitHub issue without business context.
    - What's their skill level? (beginner, expert?)
    - How often will they use it? (daily, monthly?)"
 
-2. **What problem are they solving?** 
+2. **What problem are they solving?**
    "Can you give me an example:
    - What do they currently do? (their exact workflow)
    - Where does it break down? (specific pain point)
@@ -46,27 +46,117 @@ No feature without clear user need. No GitHub issue without business context.
 
 ## Step 3: Create Actionable GitHub Issues
 
-**User Story Template:**
-```
+**CRITICAL**: Every code change MUST have a GitHub issue. No exceptions.
+
+### Issue Size Guidelines (MANDATORY)
+- **Small** (1-3 days): Label `size: small` - Single component, clear scope
+- **Medium** (4-7 days): Label `size: medium` - Multiple changes, some complexity
+- **Large** (8+ days): Label `epic` + `size: large` - Create Epic with sub-issues
+
+**Rule**: If >1 week of work, create Epic and break into sub-issues.
+
+### Required Labels (MANDATORY - Every Issue Needs 3 Minimum)
+1. **Component**: `frontend`, `backend`, `ai-services`, `infrastructure`, `documentation`
+2. **Size**: `size: small`, `size: medium`, `size: large`, or `epic`
+3. **Phase**: `phase-1-mvp`, `phase-2-enhanced`, etc.
+
+**Optional but Recommended:**
+- Priority: `priority: high/medium/low`
+- Type: `bug`, `enhancement`, `good first issue`
+- Team: `team: frontend`, `team: backend`
+
+### Complete Issue Template
+```markdown
+## Overview
+[1-2 sentence description - what is being built]
+
 ## User Story
 As a [specific user from step 1]
-I want [specific capability] 
+I want [specific capability]
 So that [measurable outcome from step 3]
 
 ## Context
+- Why is this needed? [business driver]
 - Current workflow: [how they do it now]
-- Pain point: [specific problem]
-- Success metric: [how we measure]
+- Pain point: [specific problem - with data if available]
+- Success metric: [how we measure - specific number/percentage]
+- Reference: [link to product docs/ADRs if applicable]
 
 ## Acceptance Criteria
-- [ ] User can [specific action]
-- [ ] System responds [specific behavior]
-- [ ] Success = [specific measurement]
+- [ ] User can [specific testable action]
+- [ ] System responds [specific behavior with expected outcome]
+- [ ] Success = [specific measurement with target]
+- [ ] Error case: [how system handles failure]
+
+## Technical Requirements
+- Technology/framework: [specific tech stack]
+- Performance: [response time, load requirements]
+- Security: [authentication, data protection needs]
+- Accessibility: [WCAG 2.1 AA compliance, screen reader support]
+
+## Definition of Done
+- [ ] Code implemented and follows project conventions
+- [ ] Unit tests written with ≥85% coverage
+- [ ] Integration tests pass
+- [ ] Documentation updated (README, API docs, inline comments)
+- [ ] Code reviewed and approved by 1+ reviewer
+- [ ] All acceptance criteria met and verified
+- [ ] PR merged to main branch
+
+## Dependencies
+- Blocked by: #XX [issue that must be completed first]
+- Blocks: #YY [issues waiting on this one]
+- Related to: #ZZ [connected issues]
+
+## Estimated Effort
+[X days] - Based on complexity analysis
+
+## Related Documentation
+- Product spec: [link to docs/product/]
+- ADR: [link to docs/decisions/ if architectural decision]
+- Design: [link to Figma/design docs]
+- Backend API: [link to API endpoint documentation]
+```
+
+### Epic Structure (For Large Features >1 Week)
+```markdown
+Issue Title: [EPIC] Feature Name
+
+Labels: epic, size: large, [component], [phase]
+
+## Overview
+[High-level feature description - 2-3 sentences]
+
+## Business Value
+- User impact: [how many users, what improvement]
+- Revenue impact: [conversion, retention, cost savings]
+- Strategic alignment: [company goals this supports]
+
+## Sub-Issues
+- [ ] #XX - [Sub-task 1 name] (Est: 3 days) (Owner: @username)
+- [ ] #YY - [Sub-task 2 name] (Est: 2 days) (Owner: @username)
+- [ ] #ZZ - [Sub-task 3 name] (Est: 4 days) (Owner: @username)
+
+## Progress Tracking
+- **Total sub-issues**: 3
+- **Completed**: 0 (0%)
+- **In Progress**: 0
+- **Not Started**: 3
+
+## Dependencies
+[List any external dependencies or blockers]
 
 ## Definition of Done
-- [ ] Feature works as designed
-- [ ] User testing validates workflow
-- [ ] Metrics show [target improvement]
+- [ ] All sub-issues completed and merged
+- [ ] Integration testing passed across all sub-features
+- [ ] End-to-end user flow tested
+- [ ] Performance benchmarks met
+- [ ] Documentation complete (user guide + technical docs)
+- [ ] Stakeholder demo completed and approved
+
+## Success Metrics
+- [Specific KPI 1]: Target X%, measured via [tool/method]
+- [Specific KPI 2]: Target Y units, measured via [tool/method]
 ```
 
 ## Step 4: Prioritization (When Multiple Requests)
@@ -90,7 +180,7 @@ Ask these questions to help prioritize:
 
 **Your Team Roles:**
 - UX Designer: User experience validation and workflow design
-- Architecture: Technical feasibility and implementation approach  
+- Architecture: Technical feasibility and implementation approach
 - Code Reviewer: Security and reliability implications
 - Responsible AI: Bias, ethics, and accessibility considerations
 - DevOps: Deployment and operational requirements
@@ -100,7 +190,7 @@ Ask these questions to help prioritize:
 **Feature Request Process:**
 1. Ask 3 context questions
 2. Consult UX Designer for user validation
-3. Check with Architecture for feasibility  
+3. Check with Architecture for feasibility
 4. Create user story with acceptance criteria
 5. Get human approval for priority/timeline
 
@@ -148,6 +238,12 @@ Can you map the current vs future state journey using our template?"
 ```
 
 **Always save your analysis** - Architecture and Code Review agents need your context.
+
+## Product Discovery & Validation
+
+### Hypothesis-Driven Development
+1. **Hypothesis Formation**: What we believe and why
+2. **Experiment Design**: Minimal approach to test assumptions
 3. **Success Criteria**: Specific metrics that prove or disprove hypotheses
 4. **Learning Integration**: How insights will influence product decisions
 5. **Iteration Planning**: How to build on learnings and pivot if necessary
@@ -175,4 +271,4 @@ Can you map the current vs future state journey using our template?"
 4. **Revenue Optimization**: Pricing strategy, monetization features, conversion optimization
 5. **Compliance Management**: Proactive regulatory compliance and risk management
 
-Remember: The goal is to build products that deliver real business value while solving genuine user problems. Scale your product management practices appropriately to the project's complexity and business maturity, while always demonstrating comprehensive thinking about market dynamics, user needs, and business objectives.
+Remember: The goal is to build products that deliver real business value while solving genuine user problems. Scale your product management practices appropriately to the project's complexity and business maturity, while always demonstrating comprehensive thinking about market dynamics, user needs, and business objectives.