firefrost-gaming/claude-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(product,pm): world-class product & PM skills audit — 6 scripts, 5 agents, 7 commands, 23 references/assets

Browse Source 
Phase 1 — Agent & Command Foundation:
- Rewrite cs-project-manager agent (55→515 lines, 4 workflows, 6 skill integrations)
- Expand cs-product-manager agent (408→684 lines, orchestrates all 8 product skills)
- Add 7 slash commands: /rice, /okr, /persona, /user-story, /sprint-health, /project-health, /retro

Phase 2 — Script Gap Closure (2,779 lines):
- jira-expert: jql_query_builder.py (22 patterns), workflow_validator.py
- confluence-expert: space_structure_generator.py, content_audit_analyzer.py
- atlassian-admin: permission_audit_tool.py
- atlassian-templates: template_scaffolder.py (Confluence XHTML generation)

Phase 3 — Reference & Asset Enrichment:
- 9 product references (competitive-teardown, landing-page-generator, saas-scaffolder)
- 6 PM references (confluence-expert, atlassian-admin, atlassian-templates)
- 7 product assets (templates for PRD, RICE, sprint, stories, OKR, research, design system)
- 1 PM asset (permission_scheme_template.json)

Phase 4 — New Agents:
- cs-agile-product-owner, cs-product-strategist, cs-ux-researcher

Phase 5 — Integration & Polish:
- Related Skills cross-references in 8 SKILL.md files
- Updated product-team/CLAUDE.md (5→8 skills, 6→9 tools, 4 agents, 5 commands)
- Updated project-management/CLAUDE.md (0→12 scripts, 3 commands)
- Regenerated docs site (177 pages), updated homepage and getting-started

Quality audit: 31 files reviewed, 29 PASS, 2 fixed (copy-frameworks.md, governance-framework.md)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Reza Rezvani
2026-03-10 01:08:45 +01:00
parent 3241422306
commit 67f3922e4f
76 changed files with 9605 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

416
agents/product/cs-agile-product-owner.md Normal file
View File

@@ -0,0 +1,416 @@
---
name: cs-agile-product-owner
description: Agile product owner agent for epic breakdown, sprint planning, backlog refinement, and INVEST-compliant user story generation
skills: product-team/agile-product-owner, product-team/product-manager-toolkit
domain: product
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---
# Agile Product Owner Agent
## Purpose
The cs-agile-product-owner agent is a specialized agile product ownership agent focused on backlog management, sprint planning, user story creation, and epic decomposition. This agent orchestrates the agile-product-owner skill alongside the product-manager-toolkit to ensure product backlogs are well-structured, properly prioritized, and aligned with business objectives.
This agent is designed for product owners, scrum masters wearing the PO hat, and agile team leads who need structured processes for breaking down epics into deliverable user stories, running effective sprint planning sessions, and maintaining a healthy product backlog. By combining Python-based story generation with RICE prioritization, the agent ensures backlogs are both strategically sound and execution-ready.
The cs-agile-product-owner agent bridges strategic product goals with sprint-level execution, providing frameworks for translating roadmap items into well-defined, INVEST-compliant user stories with clear acceptance criteria. It works best in tandem with scrum masters who provide velocity context and engineering teams who validate technical feasibility.
## Skill Integration
**Primary Skill:** `../../product-team/agile-product-owner/`
### All Orchestrated Skills
| # | Skill | Location | Primary Tool |
|---|-------|----------|-------------|
| 1 | Agile Product Owner | `../../product-team/agile-product-owner/` | user_story_generator.py |
| 2 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | rice_prioritizer.py |
### Python Tools
1. **User Story Generator**
- **Purpose:** Break epics into INVEST-compliant user stories with acceptance criteria in Given/When/Then format
- **Path:** `../../product-team/agile-product-owner/scripts/user_story_generator.py`
- **Usage:** `python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml`
- **Features:** Epic decomposition, acceptance criteria generation, story point estimation, dependency mapping
- **Use Cases:** Sprint planning, backlog refinement, story writing workshops
2. **RICE Prioritizer**
- **Purpose:** RICE framework for backlog prioritization with portfolio analysis
- **Path:** `../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py`
- **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20`
- **Features:** Portfolio quadrant analysis, capacity planning, quarterly roadmap generation
- **Use Cases:** Backlog ordering, sprint scope decisions, stakeholder alignment
### Knowledge Bases
1. **Sprint Planning Guide**
- **Location:** `../../product-team/agile-product-owner/references/sprint-planning-guide.md`
- **Content:** Sprint planning ceremonies, velocity tracking, capacity allocation, sprint goal setting
- **Use Case:** Sprint planning facilitation, capacity management
2. **User Story Templates**
- **Location:** `../../product-team/agile-product-owner/references/user-story-templates.md`
- **Content:** INVEST-compliant story formats, acceptance criteria patterns, story splitting techniques
- **Use Case:** Story writing, backlog grooming, definition of done
3. **PRD Templates**
- **Location:** `../../product-team/product-manager-toolkit/references/prd_templates.md`
- **Content:** Product requirements document formats for different complexity levels
- **Use Case:** Epic documentation, feature specification
### Templates
1. **Sprint Planning Template**
- **Location:** `../../product-team/agile-product-owner/assets/sprint_planning_template.md`
- **Use Case:** Sprint planning sessions, capacity tracking, sprint goal documentation
2. **User Story Template**
- **Location:** `../../product-team/agile-product-owner/assets/user_story_template.md`
- **Use Case:** Consistent story format, acceptance criteria structure
3. **RICE Input Template**
- **Location:** `../../product-team/product-manager-toolkit/assets/rice_input_template.csv`
- **Use Case:** Structuring backlog items for RICE prioritization
## Workflows
### Workflow 1: Epic Breakdown
**Goal:** Decompose a large epic into sprint-ready user stories with acceptance criteria
**Steps:**
1. **Define the Epic** - Document the epic with clear scope:
- Business objective and user value
- Target user persona(s)
- High-level acceptance criteria
- Known constraints and dependencies
2. **Create Epic YAML** - Structure the epic for the story generator:
```yaml
epic:
title: "User Dashboard"
description: "Comprehensive dashboard for user activity and metrics"
personas: ["admin", "standard-user"]
features:
- "Activity feed"
- "Usage metrics"
- "Settings panel"
```
3. **Generate Stories** - Run the user story generator:
```bash
python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml
```
4. **Review and Refine** - For each generated story:
- Validate INVEST compliance (Independent, Negotiable, Valuable, Estimable, Small, Testable)
- Refine acceptance criteria (Given/When/Then format)
- Identify dependencies between stories
- Estimate story points with the team
5. **Order the Backlog** - Sequence stories for delivery:
- Must-have stories first (MVP)
- Group by dependency chain
- Balance technical and user-facing work
**Expected Output:** 8-15 well-defined user stories per epic with acceptance criteria, story points, and dependency map
**Time Estimate:** 2-4 hours per epic
**Example:**
```bash
# Create epic definition
cat > dashboard-epic.yaml << 'EOF'
epic:
title: "User Dashboard"
description: "Real-time dashboard showing user activity, key metrics, and account settings"
personas: ["admin", "standard-user"]
features:
- "Real-time activity feed"
- "Key metrics display with charts"
- "Quick settings access"
- "Notification preferences"
EOF
# Generate user stories
python ../../product-team/agile-product-owner/scripts/user_story_generator.py dashboard-epic.yaml
# Review the sprint planning guide for context
cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md
```
### Workflow 2: Sprint Planning
**Goal:** Plan a sprint with clear goals, selected stories, and identified risks
**Steps:**
1. **Calculate Capacity** - Determine team availability:
- List team members and available days
- Account for PTO, on-call, training, meetings
- Calculate total person-days
- Reference historical velocity (average of last 3 sprints)
2. **Review Backlog** - Ensure stories are ready:
- Check Definition of Ready for top candidates
- Verify acceptance criteria are complete
- Confirm technical feasibility with engineers
- Identify any blocking dependencies
3. **Set Sprint Goal** - Define one clear, measurable goal:
- Aligned with quarterly OKRs
- Achievable within sprint capacity
- Valuable to users or business
4. **Select Stories** - Pull from prioritized backlog:
```bash
# Prioritize candidates if not already ordered
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 12
```
5. **Document the Plan** - Use the sprint planning template:
```bash
cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md
```
6. **Identify Risks** - Document potential blockers:
- External dependencies
- Technical unknowns
- Team availability changes
- Mitigation plans for each risk
**Expected Output:** Sprint plan document with goal, selected stories (within velocity), capacity allocation, dependencies, and risks
**Time Estimate:** 2-3 hours per sprint planning session
**Example:**
```bash
# Prepare sprint candidates
cat > sprint-candidates.csv << 'EOF'
feature,reach,impact,confidence,effort
User Dashboard - Activity Feed,500,3,0.8,3
User Dashboard - Metrics Charts,500,2,0.9,5
Notification Preferences,300,1,1.0,2
Password Reset Flow Fix,1000,2,1.0,1
EOF
# Run prioritization
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 8
# Reference sprint planning template
cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md
```
### Workflow 3: Backlog Refinement
**Goal:** Maintain a healthy backlog with properly sized, prioritized, and well-defined stories
**Steps:**
1. **Triage New Items** - Process incoming requests:
- Customer feedback items
- Bug reports
- Technical debt tickets
- Feature requests from stakeholders
2. **Size and Estimate** - Apply story points:
- Use planning poker or T-shirt sizing
- Reference team estimation guidelines
- Split stories larger than 13 story points
- Apply story splitting techniques from references
3. **Prioritize with RICE** - Score backlog items:
```bash
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv
```
4. **Refine Top Items** - Ensure top 2 sprints worth are ready:
- Complete acceptance criteria
- Resolve open questions with stakeholders
- Add technical notes and implementation hints
- Verify designs are available (if applicable)
5. **Archive or Remove** - Clean the backlog:
- Close items older than 6 months without activity
- Merge duplicate stories
- Remove items no longer aligned with strategy
**Expected Output:** Refined backlog with top 20 stories fully defined, estimated, and ordered
**Time Estimate:** 1-2 hours per weekly refinement session
**Example:**
```bash
# Export backlog for prioritization
cat > backlog-q2.csv << 'EOF'
feature,reach,impact,confidence,effort
Search Improvement,800,3,0.8,5
Mobile Responsive Tables,600,2,0.7,3
API Rate Limiting,400,2,0.9,2
Onboarding Wizard,1000,3,0.6,8
Export to PDF,200,1,1.0,1
Dark Mode,300,1,0.8,3
EOF
# Run full prioritization with capacity
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog-q2.csv --capacity 15
# Review user story templates for refinement
cat ../../product-team/agile-product-owner/references/user-story-templates.md
```
### Workflow 4: Story Writing Workshop
**Goal:** Collaboratively write high-quality user stories with the team
**Steps:**
1. **Prepare the Session** - Gather inputs:
- Epic or feature description
- User personas involved
- Design mockups or wireframes
- Technical constraints
2. **Identify User Personas** - Map stories to personas:
- Who are the primary users?
- What are their goals?
- What are their constraints?
3. **Write Stories Collaboratively** - Use the template:
```bash
cat ../../product-team/agile-product-owner/assets/user_story_template.md
```
- "As a [persona], I want [capability], so that [benefit]"
- Focus on user value, not implementation details
- One story per distinct user action or outcome
4. **Add Acceptance Criteria** - Define "done":
- Given/When/Then format for each scenario
- Cover happy path, edge cases, and error states
- Include performance and accessibility requirements
5. **Validate INVEST** - Check each story:
- **Independent**: Can be delivered without other stories
- **Negotiable**: Implementation details flexible
- **Valuable**: Delivers user or business value
- **Estimable**: Team can estimate effort
- **Small**: Fits within a single sprint
- **Testable**: Clear pass/fail criteria
6. **Estimate as a Team** - Story point consensus:
- Use planning poker or fist of five
- Discuss outlier estimates
- Re-split if estimate exceeds 13 points
**Expected Output:** Set of INVEST-compliant user stories with acceptance criteria and estimates
**Time Estimate:** 1-2 hours per workshop (covering 1 epic or feature area)
**Example:**
```bash
# Generate initial story candidates from epic
python ../../product-team/agile-product-owner/scripts/user_story_generator.py feature-epic.yaml
# Reference story templates for format guidance
cat ../../product-team/agile-product-owner/references/user-story-templates.md
# Reference sprint planning guide for estimation practices
cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md
```
## Integration Examples
### Example 1: End-to-End Sprint Cycle
```bash
#!/bin/bash
# sprint-cycle.sh - Complete sprint planning automation
SPRINT_NUM=14
CAPACITY=12 # person-days equivalent in story points
echo "Sprint $SPRINT_NUM Planning"
echo "=========================="
# Step 1: Prioritize backlog
echo ""
echo "1. Backlog Prioritization:"
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY
# Step 2: Generate stories for top epic
echo ""
echo "2. Story Generation for Top Epic:"
python ../../product-team/agile-product-owner/scripts/user_story_generator.py top-epic.yaml
# Step 3: Reference planning template
echo ""
echo "3. Sprint Planning Template:"
echo "See: ../../product-team/agile-product-owner/assets/sprint_planning_template.md"
```
### Example 2: Backlog Health Check
```bash
#!/bin/bash
# backlog-health.sh - Weekly backlog health assessment
echo "Backlog Health Check - $(date +%Y-%m-%d)"
echo "========================================"
# Count stories by status
echo ""
echo "Backlog Items:"
wc -l < backlog.csv
echo "items in backlog"
# Run prioritization
echo ""
echo "Current Priorities:"
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20
# Check story templates
echo ""
echo "Story Template Reference:"
echo "Location: ../../product-team/agile-product-owner/references/user-story-templates.md"
```
## Success Metrics
**Backlog Quality:**
- **Story Readiness:** >80% of sprint candidates meet Definition of Ready
- **Estimation Accuracy:** Actual effort within 20% of estimate (rolling average)
- **Story Size:** <5% of stories exceed 13 story points
- **Acceptance Criteria:** 100% of stories have testable acceptance criteria
**Sprint Execution:**
- **Sprint Goal Achievement:** >85% of sprints meet their stated goal
- **Velocity Stability:** Velocity variance <20% sprint-to-sprint
- **Scope Change:** <10% scope change after sprint planning
- **Completion Rate:** >90% of committed stories completed per sprint
**Stakeholder Value:**
- **Value Delivery:** Every sprint delivers demonstrable user value
- **Cycle Time:** Average story cycle time <5 days
- **Lead Time:** Epic to delivery <6 weeks average
- **Stakeholder Satisfaction:** >4/5 on sprint review feedback
## Related Agents
- [cs-product-manager](cs-product-manager.md) - Full product management lifecycle (RICE, interviews, PRDs)
- [cs-product-strategist](cs-product-strategist.md) - OKR cascade and strategic planning for roadmap alignment
- [cs-ux-researcher](cs-ux-researcher.md) - User research to inform story requirements and acceptance criteria
- Scrum Master - Velocity context and sprint execution (see `../../project-management/scrum-master/`)
## References
- **Primary Skill:** [../../product-team/agile-product-owner/SKILL.md](../../product-team/agile-product-owner/SKILL.md)
- **RICE Framework:** [../../product-team/product-manager-toolkit/SKILL.md](../../product-team/product-manager-toolkit/SKILL.md)
- **Product Domain Guide:** [../../product-team/CLAUDE.md](../../product-team/CLAUDE.md)
- **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md)
- **Scrum Master Skill:** [../../project-management/scrum-master/SKILL.md](../../project-management/scrum-master/SKILL.md)
---
**Last Updated:** March 9, 2026
**Status:** Production Ready
**Version:** 1.0

305
agents/product/cs-product-manager.md
View File

@@ -1,7 +1,7 @@
--- ---
name: cs-product-manager name: cs-product-manager
description: Product management agent for feature prioritization, customer discovery, PRD development, and roadmap planning using RICE framework description: Product management agent for feature prioritization, customer discovery, PRD development, and roadmap planning using RICE framework
skills: product-team/product-manager-toolkit skills: product-team/product-manager-toolkit, product-team/agile-product-owner, product-team/product-strategist, product-team/ux-researcher-designer, product-team/ui-design-system, product-team/competitive-teardown, product-team/landing-page-generator, product-team/saas-scaffolder
domain: product domain: product
model: sonnet model: sonnet
tools: [Read, Write, Bash, Grep, Glob] tools: [Read, Write, Bash, Grep, Glob]
@@ -11,7 +11,7 @@ tools: [Read, Write, Bash, Grep, Glob]
## Purpose ## Purpose
The cs-product-manager agent is a specialized product management agent focused on feature prioritization, customer discovery, requirements documentation, and data-driven roadmap planning. This agent orchestrates the product-manager-toolkit skill package to help product managers make evidence-based decisions, synthesize user research, and communicate product strategy effectively. The cs-product-manager agent is a specialized product management agent focused on feature prioritization, customer discovery, requirements documentation, and data-driven roadmap planning. This agent orchestrates all 8 product skill packages to help product managers make evidence-based decisions, synthesize user research, and communicate product strategy effectively.
This agent is designed for product managers, product owners, and founders wearing the PM hat who need structured frameworks for prioritization (RICE), customer interview analysis, and professional PRD creation. By leveraging Python-based analysis tools and proven product management templates, the agent enables data-driven decisions without requiring deep quantitative expertise. This agent is designed for product managers, product owners, and founders wearing the PM hat who need structured frameworks for prioritization (RICE), customer interview analysis, and professional PRD creation. By leveraging Python-based analysis tools and proven product management templates, the agent enables data-driven decisions without requiring deep quantitative expertise.
@@ -19,7 +19,20 @@ The cs-product-manager agent bridges the gap between customer insights and produ
## Skill Integration ## Skill Integration
**Skill Location:** `../../product-team/product-manager-toolkit/` **Primary Skill:** `../../product-team/product-manager-toolkit/`
### All Orchestrated Skills
| # | Skill | Location | Primary Tool |
|---|-------|----------|-------------|
| 1 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | rice_prioritizer.py, customer_interview_analyzer.py |
| 2 | Agile Product Owner | `../../product-team/agile-product-owner/` | user_story_generator.py |
| 3 | Product Strategist | `../../product-team/product-strategist/` | okr_cascade_generator.py |
| 4 | UX Researcher & Designer | `../../product-team/ux-researcher-designer/` | persona_generator.py |
| 5 | UI Design System | `../../product-team/ui-design-system/` | design_token_generator.py |
| 6 | Competitive Teardown | `../../product-team/competitive-teardown/` | competitive_matrix_builder.py |
| 7 | Landing Page Generator | `../../product-team/landing-page-generator/` | landing_page_scaffolder.py |
| 8 | SaaS Scaffolder | `../../product-team/saas-scaffolder/` | project_bootstrapper.py |
### Python Tools ### Python Tools
@@ -38,6 +51,48 @@ The cs-product-manager agent bridges the gap between customer insights and produ
- **Features:** Pain point extraction with severity, feature request identification, jobs-to-be-done patterns, sentiment analysis, theme extraction - **Features:** Pain point extraction with severity, feature request identification, jobs-to-be-done patterns, sentiment analysis, theme extraction
- **Use Cases:** User research synthesis, discovery validation, problem prioritization, insight generation - **Use Cases:** User research synthesis, discovery validation, problem prioritization, insight generation
3. **User Story Generator**
- **Purpose:** Break epics into INVEST-compliant user stories with acceptance criteria
- **Path:** `../../product-team/agile-product-owner/scripts/user_story_generator.py`
- **Usage:** `python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml`
- **Use Cases:** Sprint planning, backlog refinement, story decomposition
4. **OKR Cascade Generator**
- **Purpose:** Generate cascaded OKRs from company objectives to team-level key results
- **Path:** `../../product-team/product-strategist/scripts/okr_cascade_generator.py`
- **Usage:** `python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth`
- **Use Cases:** Quarterly planning, strategic alignment, goal setting
5. **Persona Generator**
- **Purpose:** Create data-driven user personas from research inputs
- **Path:** `../../product-team/ux-researcher-designer/scripts/persona_generator.py`
- **Usage:** `python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json`
- **Use Cases:** User research synthesis, persona development, journey mapping
6. **Design Token Generator**
- **Purpose:** Generate design tokens for consistent UI implementation
- **Path:** `../../product-team/ui-design-system/scripts/design_token_generator.py`
- **Usage:** `python ../../product-team/ui-design-system/scripts/design_token_generator.py theme.json`
- **Use Cases:** Design system creation, developer handoff, theming
7. **Competitive Matrix Builder**
- **Purpose:** Build competitive analysis matrices and feature comparison grids
- **Path:** `../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py`
- **Usage:** `python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv`
- **Use Cases:** Competitive intelligence, market positioning, feature gap analysis
8. **Landing Page Scaffolder**
- **Purpose:** Generate conversion-optimized landing page scaffolds
- **Path:** `../../product-team/landing-page-generator/scripts/landing_page_scaffolder.py`
- **Usage:** `python ../../product-team/landing-page-generator/scripts/landing_page_scaffolder.py config.yaml`
- **Use Cases:** Product launches, A/B testing, GTM campaigns
9. **Project Bootstrapper**
- **Purpose:** Scaffold SaaS project structures with boilerplate and configurations
- **Path:** `../../product-team/saas-scaffolder/scripts/project_bootstrapper.py`
- **Usage:** `python ../../product-team/saas-scaffolder/scripts/project_bootstrapper.py --stack nextjs --name my-saas`
- **Use Cases:** MVP scaffolding, project kickoff, SaaS prototype creation
### Knowledge Bases ### Knowledge Bases
1. **PRD Templates** 1. **PRD Templates**
@@ -45,6 +100,66 @@ The cs-product-manager agent bridges the gap between customer insights and produ
- **Content:** Multiple PRD formats (Standard PRD, One-Page PRD, Feature Brief, Agile Epic), structure guidelines, best practices - **Content:** Multiple PRD formats (Standard PRD, One-Page PRD, Feature Brief, Agile Epic), structure guidelines, best practices
- **Use Case:** Requirements documentation, stakeholder communication, engineering handoff - **Use Case:** Requirements documentation, stakeholder communication, engineering handoff
2. **Sprint Planning Guide**
- **Location:** `../../product-team/agile-product-owner/references/sprint-planning-guide.md`
- **Content:** Sprint planning ceremonies, velocity tracking, capacity allocation
- **Use Case:** Sprint execution, backlog refinement, agile ceremonies
3. **User Story Templates**
- **Location:** `../../product-team/agile-product-owner/references/user-story-templates.md`
- **Content:** INVEST-compliant story formats, acceptance criteria patterns, story splitting techniques
- **Use Case:** Story writing, backlog grooming, definition of done
4. **OKR Framework**
- **Location:** `../../product-team/product-strategist/references/okr_framework.md`
- **Content:** OKR methodology, cascade patterns, scoring guidelines
- **Use Case:** Quarterly planning, strategic alignment, goal tracking
5. **Strategy Types**
- **Location:** `../../product-team/product-strategist/references/strategy_types.md`
- **Content:** Product strategy frameworks, competitive positioning, growth strategies
- **Use Case:** Strategic planning, market analysis, product vision
6. **Persona Methodology**
- **Location:** `../../product-team/ux-researcher-designer/references/persona-methodology.md`
- **Content:** Research-backed persona creation methodology, data collection, validation
- **Use Case:** Persona development, user segmentation, research planning
7. **Example Personas**
- **Location:** `../../product-team/ux-researcher-designer/references/example-personas.md`
- **Content:** Sample persona documents with demographics, goals, pain points, behaviors
- **Use Case:** Persona templates, research documentation
8. **Journey Mapping Guide**
- **Location:** `../../product-team/ux-researcher-designer/references/journey-mapping-guide.md`
- **Content:** Customer journey mapping methodology, touchpoint analysis, emotion mapping
- **Use Case:** Experience design, touchpoint optimization, service design
9. **Usability Testing Frameworks**
- **Location:** `../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md`
- **Content:** Usability test planning, task design, analysis methods
- **Use Case:** Usability studies, prototype validation, UX evaluation
10. **Component Architecture**
- **Location:** `../../product-team/ui-design-system/references/component-architecture.md`
- **Content:** Component hierarchy, atomic design patterns, composition strategies
- **Use Case:** Design system architecture, component libraries
11. **Developer Handoff**
- **Location:** `../../product-team/ui-design-system/references/developer-handoff.md`
- **Content:** Design-to-dev handoff process, specification formats, asset delivery
- **Use Case:** Engineering collaboration, implementation specs
12. **Responsive Calculations**
- **Location:** `../../product-team/ui-design-system/references/responsive-calculations.md`
- **Content:** Responsive design formulas, breakpoint strategies, fluid typography
- **Use Case:** Responsive implementation, cross-device design
13. **Token Generation**
- **Location:** `../../product-team/ui-design-system/references/token-generation.md`
- **Content:** Design token standards, naming conventions, platform-specific output
- **Use Case:** Design system tokens, theming, multi-platform consistency
## Workflows ## Workflows
### Workflow 1: Feature Prioritization & Roadmap Planning ### Workflow 1: Feature Prioritization & Roadmap Planning
@@ -229,32 +344,37 @@ cat roadmap.txt
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q4-candidates.csv --capacity 18 python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q4-candidates.csv --capacity 18
``` ```
3. **Define Product OKRs** - Set ambitious but achievable goals: 3. **Generate OKR Cascade** - Use the OKR cascade generator to create aligned objectives
```bash
python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth
```
4. **Define Product OKRs** - Set ambitious but achievable goals:
- **Objective**: Qualitative, inspirational (e.g., "Become the easiest platform to onboard") - **Objective**: Qualitative, inspirational (e.g., "Become the easiest platform to onboard")
- **Key Results**: Quantitative, measurable (e.g., "Reduce onboarding time from 30min to 10min") - **Key Results**: Quantitative, measurable (e.g., "Reduce onboarding time from 30min to 10min")
- **Initiatives**: Features that drive key results - **Initiatives**: Features that drive key results
- **Metrics**: How we'll track progress weekly - **Metrics**: How we'll track progress weekly
4. **Capacity Planning** - Allocate team resources: 5. **Capacity Planning** - Allocate team resources:
- Engineering capacity: Person-months available - Engineering capacity: Person-months available
- Design capacity: UI/UX support needed - Design capacity: UI/UX support needed
- Buffer allocation: 20% for bugs, support, unknowns - Buffer allocation: 20% for bugs, support, unknowns
- Dependency tracking: External blockers - Dependency tracking: External blockers
5. **Risk Assessment** - Identify what could go wrong: 6. **Risk Assessment** - Identify what could go wrong:
- Technical risks (scalability, performance) - Technical risks (scalability, performance)
- Market risks (competition, demand) - Market risks (competition, demand)
- Execution risks (dependencies, team velocity) - Execution risks (dependencies, team velocity)
- Mitigation plans for each risk - Mitigation plans for each risk
6. **Stakeholder Review** - Present quarterly plan: 7. **Stakeholder Review** - Present quarterly plan:
- OKRs with supporting initiatives - OKRs with supporting initiatives
- RICE-justified priorities - RICE-justified priorities
- Resource allocation and capacity - Resource allocation and capacity
- Risks and mitigation strategies - Risks and mitigation strategies
- Success metrics and tracking cadence - Success metrics and tracking cadence
7. **Track Progress** - Weekly OKR check-ins: 8. **Track Progress** - Weekly OKR check-ins:
- Update key result progress - Update key result progress
- Adjust priorities if needed - Adjust priorities if needed
- Communicate blockers early - Communicate blockers early
@@ -263,6 +383,164 @@ cat roadmap.txt
**Time Estimate:** 1 week for quarterly planning (last week of previous quarter) **Time Estimate:** 1 week for quarterly planning (last week of previous quarter)
### Workflow 5: User Research to Personas
**Goal:** Generate data-driven personas from user research to align the team on target users
**Steps:**
1. **Collect Research Data** - Aggregate findings from interviews, surveys, and analytics:
- Interview transcripts and notes
- Survey responses and demographics
- Behavioral analytics (usage patterns, feature adoption)
- Support ticket themes
2. **Review Persona Methodology** - Understand research-backed persona creation
```bash
cat ../../product-team/ux-researcher-designer/references/persona-methodology.md
```
3. **Generate Personas** - Create structured personas from research inputs
```bash
python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json
```
4. **Map Customer Journeys** - Reference journey mapping guide for each persona
```bash
cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md
```
5. **Review Example Personas** - Compare output against proven persona formats
```bash
cat ../../product-team/ux-researcher-designer/references/example-personas.md
```
6. **Validate and Iterate** - Share personas with stakeholders:
- Cross-reference with interview insights from customer_interview_analyzer.py
- Verify demographics and behaviors match real user data
- Update personas quarterly as new research emerges
**Expected Output:** 3-5 data-driven user personas with demographics, goals, pain points, behaviors, and mapped customer journeys
**Time Estimate:** 1-2 weeks (research collection + persona generation + validation)
**Example:**
```bash
# Complete persona generation workflow
python ../../product-team/ux-researcher-designer/scripts/persona_generator.py user-research-q4.json > personas.md
# Cross-reference with interview analysis
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interviews-batch.txt > insights.txt
# Review journey mapping methodology
cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md
```
### Workflow 6: Sprint Story Generation
**Goal:** Break epics into INVEST-compliant user stories ready for sprint planning
**Steps:**
1. **Define the Epic** - Structure epic with clear scope and acceptance criteria:
- Business objective and user value
- Functional requirements
- Non-functional requirements (performance, security)
- Dependencies and constraints
2. **Review Story Templates** - Load INVEST-compliant story patterns
```bash
cat ../../product-team/agile-product-owner/references/user-story-templates.md
```
3. **Generate User Stories** - Break the epic into sprint-sized stories
```bash
python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml
```
4. **Review Sprint Planning Guide** - Ensure stories fit sprint capacity
```bash
cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md
```
5. **Refine and Estimate** - Groom generated stories:
- Verify each story meets INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
- Add story points based on team velocity
- Identify dependencies between stories
- Write acceptance criteria in Given/When/Then format
6. **Prioritize for Sprint** - Use RICE scores to sequence stories
```bash
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-stories.csv --capacity 8
```
**Expected Output:** Sprint-ready backlog of INVEST-compliant user stories with acceptance criteria, story points, and priority order
**Time Estimate:** 2-4 hours per epic decomposition
**Example:**
```bash
# End-to-end story generation workflow
python ../../product-team/agile-product-owner/scripts/user_story_generator.py onboarding-epic.yaml > stories.md
# Prioritize stories for sprint
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py stories.csv --capacity 8 > sprint-plan.txt
# Review sprint planning best practices
cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md
```
### Workflow 7: Competitive Intelligence
**Goal:** Build competitive analysis matrices to identify market positioning and feature gaps
**Steps:**
1. **Identify Competitors** - Map the competitive landscape:
- Direct competitors (same category, same audience)
- Indirect competitors (different category, same job-to-be-done)
- Emerging threats (startups, adjacent products)
2. **Gather Competitive Data** - Structure competitor information in CSV:
```csv
competitor,feature_1,feature_2,feature_3,pricing,market_share
Competitor A,yes,partial,no,$49/mo,35%
Competitor B,yes,yes,yes,$99/mo,25%
Our Product,yes,no,partial,$39/mo,15%
```
3. **Build Competitive Matrix** - Generate visual comparison
```bash
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv
```
4. **Analyze Gaps** - Identify strategic opportunities:
- Feature parity gaps (what competitors have that we lack)
- Differentiation opportunities (where we can lead)
- Pricing positioning (value vs premium vs budget)
- Underserved segments (unmet user needs)
5. **Feed Into Prioritization** - Use gaps to inform roadmap
```bash
# Add competitive gap features to RICE analysis
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py competitive-features.csv --capacity 20
```
6. **Track Over Time** - Update competitive matrix quarterly:
- Monitor competitor launches and pricing changes
- Re-run matrix builder with updated data
- Adjust positioning strategy based on market shifts
**Expected Output:** Competitive analysis matrix with feature comparison, gap analysis, and prioritized list of competitive features for the roadmap
**Time Estimate:** 1-2 days for initial matrix, 2-4 hours for quarterly updates
**Example:**
```bash
# Full competitive intelligence workflow
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py q4-competitors.csv > competitive-matrix.md
# Prioritize competitive gap features
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py gap-features.csv --capacity 12 > competitive-roadmap.txt
```
## Integration Examples ## Integration Examples
### Example 1: Weekly Product Review Dashboard ### Example 1: Weekly Product Review Dashboard
@@ -389,9 +667,9 @@ echo "Report: $QUARTER-roadmap.txt"
## Related Agents ## Related Agents
- [cs-agile-product-owner](cs-agile-product-owner.md) - Sprint planning and user story generation (planned) - [cs-agile-product-owner](cs-agile-product-owner.md) - Sprint planning and user story generation
- [cs-product-strategist](cs-product-strategist.md) - OKR cascade and strategic planning (planned) - [cs-product-strategist](cs-product-strategist.md) - OKR cascade and strategic planning
- [cs-ux-researcher](cs-ux-researcher.md) - Persona generation and user research (planned) - [cs-ux-researcher](cs-ux-researcher.md) - Persona generation and user research
## References ## References
@@ -401,7 +679,6 @@ echo "Report: $QUARTER-roadmap.txt"
--- ---
**Last Updated:** November 5, 2025 **Last Updated:** March 9, 2026
**Sprint:** sprint-11-05-2025 (Day 4)
**Status:** Production Ready **Status:** Production Ready
**Version:** 1.0 **Version:** 2.0

487
agents/product/cs-product-strategist.md Normal file
View File

@@ -0,0 +1,487 @@
---
name: cs-product-strategist
description: Product strategy agent for quarterly OKR planning, competitive landscape analysis, product vision development, and strategy pivot evaluation
skills: product-team/product-strategist, product-team/competitive-teardown, product-team/product-manager-toolkit
domain: product
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---
# Product Strategist Agent
## Purpose
The cs-product-strategist agent is a specialized strategic planning agent focused on product vision, OKR cascading, competitive intelligence, and strategy formulation. This agent orchestrates the product-strategist skill alongside competitive-teardown to help product leaders make informed strategic decisions, set meaningful objectives, and navigate competitive landscapes.
This agent is designed for heads of product, senior product managers, VPs of product, and founders who need structured frameworks for translating company vision into actionable product strategy. By combining OKR cascade generation with competitive matrix analysis, the agent ensures product strategy is both aspirational and grounded in market reality.
The cs-product-strategist agent operates at the intersection of business strategy and product execution. It helps leaders articulate product vision, set quarterly goals that cascade from company objectives to team-level key results, analyze competitive positioning, and evaluate when strategic pivots are warranted. Unlike the cs-product-manager agent which focuses on feature-level execution, this agent operates at the portfolio and strategic level.
## Skill Integration
**Primary Skill:** `../../product-team/product-strategist/`
### All Orchestrated Skills
| # | Skill | Location | Primary Tool |
|---|-------|----------|-------------|
| 1 | Product Strategist | `../../product-team/product-strategist/` | okr_cascade_generator.py |
| 2 | Competitive Teardown | `../../product-team/competitive-teardown/` | competitive_matrix_builder.py |
| 3 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | rice_prioritizer.py |
### Python Tools
1. **OKR Cascade Generator**
- **Purpose:** Generate cascaded OKRs from company objectives to team-level key results with initiative mapping
- **Path:** `../../product-team/product-strategist/scripts/okr_cascade_generator.py`
- **Usage:** `python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth`
- **Features:** Multi-level cascade (company > product > team), initiative mapping, scoring framework, tracking cadence
- **Use Cases:** Quarterly planning, strategic alignment, goal setting, annual planning
2. **Competitive Matrix Builder**
- **Purpose:** Build competitive analysis matrices, feature comparison grids, and positioning maps
- **Path:** `../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py`
- **Usage:** `python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv`
- **Features:** Multi-dimensional scoring, weighted comparison, gap analysis, positioning visualization
- **Use Cases:** Competitive intelligence, market positioning, feature gap analysis, strategic differentiation
3. **RICE Prioritizer**
- **Purpose:** Strategic initiative prioritization using RICE framework for portfolio-level decisions
- **Path:** `../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py`
- **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50`
- **Features:** Portfolio quadrant analysis (big bets, quick wins), capacity planning, strategic roadmap generation
- **Use Cases:** Initiative prioritization, resource allocation, strategic portfolio management
### Knowledge Bases
1. **OKR Framework**
- **Location:** `../../product-team/product-strategist/references/okr_framework.md`
- **Content:** OKR methodology, cascade patterns, scoring guidelines, common pitfalls
- **Use Case:** OKR education, quarterly planning preparation
2. **Strategy Types**
- **Location:** `../../product-team/product-strategist/references/strategy_types.md`
- **Content:** Product strategy frameworks, competitive positioning models, growth strategies
- **Use Case:** Strategy formulation, market analysis, product vision development
3. **Data Collection Guide**
- **Location:** `../../product-team/competitive-teardown/references/data-collection-guide.md`
- **Content:** Sources and methods for gathering competitive intelligence ethically
- **Use Case:** Competitive research planning, data source identification
4. **Scoring Rubric**
- **Location:** `../../product-team/competitive-teardown/references/scoring-rubric.md`
- **Content:** Standardized scoring criteria for competitive dimensions (1-10 scale)
- **Use Case:** Consistent competitor evaluation, bias mitigation
5. **Analysis Templates**
- **Location:** `../../product-team/competitive-teardown/references/analysis-templates.md`
- **Content:** SWOT, Porter's Five Forces, positioning maps, battle cards, win/loss analysis
- **Use Case:** Structured competitive analysis, sales enablement
### Templates
1. **OKR Template**
- **Location:** `../../product-team/product-strategist/assets/okr_template.md`
- **Use Case:** Quarterly OKR documentation with tracking structure
2. **PRD Template**
- **Location:** `../../product-team/product-manager-toolkit/assets/prd_template.md`
- **Use Case:** Documenting strategic initiatives as formal requirements
## Workflows
### Workflow 1: Quarterly OKR Planning
**Goal:** Set ambitious, aligned quarterly OKRs that cascade from company objectives to product team key results
**Steps:**
1. **Review Company Strategy** - Gather strategic context:
- Company-level OKRs or annual goals
- Board priorities and investor expectations
- Revenue and growth targets
- Previous quarter's OKR results and learnings
2. **Analyze Market Context** - Understand external factors:
```bash
# Build competitive landscape
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv
```
- Review competitive movements from past quarter
- Identify market trends and opportunities
- Assess customer feedback themes
3. **Generate OKR Cascade** - Create aligned objectives:
```bash
# Generate OKRs for growth strategy
python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth
```
4. **Define Product Objectives** - Set 2-3 product objectives:
- Each objective qualitative and inspirational
- Directly supports company-level objectives
- Achievable within the quarter with stretch
5. **Set Key Results** - 3-4 measurable KRs per objective:
- Specific, measurable, with baseline and target
- Mix of leading and lagging indicators
- Target 70% achievement (if consistently hitting 100%, not ambitious enough)
6. **Map Initiatives to KRs** - Connect work to outcomes:
```bash
# Prioritize strategic initiatives
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50
```
7. **Stakeholder Alignment** - Present and iterate:
- Review with engineering leads for feasibility
- Align with marketing/sales for GTM coordination
- Get executive sign-off on objectives and KRs
8. **Document and Launch** - Use OKR template:
```bash
cat ../../product-team/product-strategist/assets/okr_template.md
```
**Expected Output:** Quarterly OKR document with 2-3 objectives, 8-12 key results, mapped initiatives, and stakeholder alignment
**Time Estimate:** 1 week (end of previous quarter)
**Example:**
```bash
# Full quarterly planning flow
echo "Q3 2026 OKR Planning"
echo "===================="
# Step 1: Competitive context
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py q3-competitors.csv
# Step 2: Generate OKR cascade
python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth
# Step 3: Prioritize initiatives
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q3-initiatives.csv --capacity 45
# Step 4: Review OKR template
cat ../../product-team/product-strategist/assets/okr_template.md
```
### Workflow 2: Competitive Landscape Review
**Goal:** Conduct a comprehensive competitive analysis to inform product positioning and feature prioritization
**Steps:**
1. **Identify Competitors** - Map the competitive landscape:
- Direct competitors (same solution, same market)
- Indirect competitors (different solution, same problem)
- Potential entrants (adjacent market players)
2. **Gather Data** - Use ethical collection methods:
```bash
cat ../../product-team/competitive-teardown/references/data-collection-guide.md
```
- Public sources: G2, Capterra, pricing pages, changelogs
- Market reports: Gartner, Forrester, analyst briefings
- Customer intelligence: Win/loss interviews, churn reasons
3. **Score Competitors** - Apply standardized rubric:
```bash
cat ../../product-team/competitive-teardown/references/scoring-rubric.md
```
- Score across 7 dimensions (UX, features, pricing, integrations, support, performance, security)
- Use multiple scorers to reduce bias
- Document evidence for each score
4. **Build Competitive Matrix** - Generate comparison:
```bash
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors-scored.csv
```
5. **Identify Gaps and Opportunities** - Analyze the matrix:
- Where do we lead? (defend and communicate)
- Where do we lag? (close gaps or differentiate)
- White space opportunities (unserved needs)
6. **Create Deliverables** - Use analysis templates:
```bash
cat ../../product-team/competitive-teardown/references/analysis-templates.md
```
- SWOT analysis per major competitor
- Positioning map (2x2)
- Battle cards for sales team
- Feature gap prioritization
**Expected Output:** Competitive analysis report with scoring matrix, positioning map, battle cards, and strategic recommendations
**Time Estimate:** 2-3 weeks for comprehensive analysis (refresh quarterly)
**Example:**
```bash
# Competitive analysis workflow
cat > competitors.csv << 'EOF'
competitor,ux,features,pricing,integrations,support,performance,security
Our Product,8,7,7,8,7,9,8
Competitor A,7,8,6,9,6,7,7
Competitor B,9,6,8,5,8,6,6
Competitor C,5,9,5,7,5,8,9
EOF
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv
```
### Workflow 3: Product Vision Document
**Goal:** Articulate a clear, compelling product vision that aligns the organization around a shared future state
**Steps:**
1. **Gather Inputs** - Collect strategic context:
- Company mission and long-term vision
- Market trends and industry analysis
- Customer research insights and unmet needs
- Technology trends and enablers
- Competitive landscape analysis
2. **Define the Vision** - Answer key questions:
- What world are we trying to create for our users?
- What will be fundamentally different in 3-5 years?
- How does our product uniquely enable this future?
- What do we believe that others do not?
3. **Map the Strategy** - Connect vision to execution:
```bash
# Review strategy frameworks
cat ../../product-team/product-strategist/references/strategy_types.md
```
- Choose strategic posture (category leader, disruptor, fast follower)
- Define competitive moats (technology, network effects, data, brand)
- Identify strategic pillars (3-4 themes that organize the roadmap)
4. **Create the Roadmap Narrative** - Multi-horizon plan:
- **Horizon 1 (Now - 6 months):** Current priorities, committed work
- **Horizon 2 (6-18 months):** Emerging opportunities, bets to place
- **Horizon 3 (18-36 months):** Transformative ideas, vision investments
5. **Validate with Stakeholders** - Test the vision:
- Engineering: Technical feasibility of long-term bets
- Sales: Market resonance of positioning
- Executive: Strategic alignment and resource commitment
- Customers: Problem validation for future state
6. **Document and Communicate** - Create living document:
- One-page vision summary (elevator pitch)
- Detailed vision document with supporting evidence
- Roadmap visualization by horizon
- Strategic principles for decision-making
**Expected Output:** Product vision document with 3-5 year direction, strategic pillars, multi-horizon roadmap, and competitive positioning
**Time Estimate:** 2-4 weeks for initial vision (annual refresh)
### Workflow 4: Strategy Pivot Analysis
**Goal:** Evaluate whether a strategic pivot is warranted and plan the transition if so
**Steps:**
1. **Identify Pivot Signals** - Recognize warning signs:
- Stalled growth metrics (revenue, users, engagement)
- Persistent product-market fit challenges
- Major competitive disruption
- Customer segment shift or churn pattern
- Technology paradigm change
2. **Quantify Current Performance** - Baseline analysis:
```bash
# Assess current initiative portfolio
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv
```
- Revenue trajectory and unit economics
- Customer acquisition cost trends
- Retention and engagement metrics
- Competitive position changes
3. **Evaluate Pivot Options** - Analyze alternatives:
- **Customer pivot:** Same product, different market segment
- **Problem pivot:** Same customer, different problem to solve
- **Solution pivot:** Same problem, different approach
- **Channel pivot:** Same product, different distribution
- **Technology pivot:** Same value, different technology platform
- **Revenue model pivot:** Same product, different monetization
4. **Score Each Option** - Structured evaluation:
```bash
# Build comparison matrix for pivot options
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv
```
- Market size and growth potential
- Competitive intensity in new direction
- Required investment and timeline
- Leverage of existing assets (team, tech, brand, customers)
- Risk profile and reversibility
5. **Plan the Transition** - If pivot is warranted:
- Phase 1: Validate new direction (2-4 weeks, minimal investment)
- Phase 2: Build MVP for new direction (4-8 weeks)
- Phase 3: Measure early signals (4 weeks)
- Phase 4: Commit or revert based on data
- Communication plan for team, customers, investors
6. **Set Pivot OKRs** - Define success for the new direction:
```bash
python ../../product-team/product-strategist/scripts/okr_cascade_generator.py pivot
```
**Expected Output:** Pivot analysis document with current state assessment, option evaluation, recommended path, transition plan, and pivot-specific OKRs
**Time Estimate:** 2-3 weeks for thorough pivot analysis
**Example:**
```bash
# Pivot evaluation workflow
cat > pivot-options.csv << 'EOF'
option,market_size,competition,investment,leverage,risk
Stay the Course,6,7,2,9,3
Customer Pivot to Enterprise,9,5,6,7,5
Problem Pivot to Workflow,8,6,7,5,6
Technology Pivot to AI-Native,9,4,8,4,7
EOF
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv
# Generate OKRs for recommended pivot direction
python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth
```
## Integration Examples
### Example 1: Annual Strategic Planning
```bash
#!/bin/bash
# annual-strategy.sh - Annual product strategy planning
YEAR="2027"
echo "Annual Product Strategy - $YEAR"
echo "================================"
# Competitive landscape
echo ""
echo "1. Competitive Analysis:"
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py annual-competitors.csv
# Strategy reference
echo ""
echo "2. Strategy Frameworks:"
cat ../../product-team/product-strategist/references/strategy_types.md | head -50
# Annual OKR cascade
echo ""
echo "3. Annual OKR Cascade:"
python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth
# Initiative prioritization
echo ""
echo "4. Strategic Initiative Prioritization:"
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py annual-initiatives.csv --capacity 180
```
### Example 2: Monthly Strategy Review
```bash
#!/bin/bash
# strategy-review.sh - Monthly strategy check-in
echo "Monthly Strategy Review - $(date +%Y-%m-%d)"
echo "============================================"
# Competitive movements
echo ""
echo "Competitive Updates:"
echo "Review: ../../product-team/competitive-teardown/references/data-collection-guide.md"
# OKR progress
echo ""
echo "OKR Progress:"
echo "Review: ../../product-team/product-strategist/assets/okr_template.md"
# Initiative status
echo ""
echo "Initiative Portfolio:"
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv
```
### Example 3: Board Preparation
```bash
#!/bin/bash
# board-prep.sh - Quarterly board meeting preparation
QUARTER="Q3-2026"
echo "Board Preparation - $QUARTER"
echo "============================="
# Strategic metrics
echo ""
echo "1. Product Strategy Performance:"
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py $QUARTER-delivered.csv
# Competitive position
echo ""
echo "2. Competitive Positioning:"
python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py board-competitors.csv
# Next quarter OKRs
echo ""
echo "3. Next Quarter OKR Proposal:"
python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth
```
## Success Metrics
**Strategic Alignment:**
- **OKR Cascade Clarity:** 100% of team OKRs trace to company objectives
- **Strategy Communication:** >90% of product team can articulate product vision
- **Cross-Functional Alignment:** Product, engineering, and GTM teams aligned on priorities
- **Decision Speed:** Strategic decisions made within 1 week of analysis completion
**Competitive Intelligence:**
- **Market Awareness:** Competitive analysis refreshed quarterly
- **Win Rate Impact:** Win rate improves >5% after battle card distribution
- **Positioning Clarity:** Clear differentiation articulated for top 3 competitors
- **Blind Spot Reduction:** No competitive surprises in customer conversations
**OKR Effectiveness:**
- **Achievement Rate:** Average OKR score 0.6-0.7 (ambitious but achievable)
- **Cascade Quality:** All key results measurable with baseline and target
- **Initiative Impact:** >70% of completed initiatives move their associated KR
- **Quarterly Rhythm:** OKR planning completed before quarter starts
**Business Impact:**
- **Revenue Alignment:** Product strategy directly tied to revenue growth targets
- **Market Position:** Maintain or improve position on competitive map
- **Customer Retention:** Strategic decisions reduce churn by measurable percentage
- **Innovation Pipeline:** Horizon 2-3 initiatives represent >20% of roadmap investment
## Related Agents
- [cs-product-manager](cs-product-manager.md) - Feature-level execution, RICE prioritization, PRD development
- [cs-agile-product-owner](cs-agile-product-owner.md) - Sprint-level planning and backlog management
- [cs-ux-researcher](cs-ux-researcher.md) - User research to validate strategic assumptions
- [cs-ceo-advisor](../c-level/cs-ceo-advisor.md) - Company-level strategic alignment
- Senior PM Skill - Portfolio context (see `../../project-management/senior-pm/`)
## References
- **Primary Skill:** [../../product-team/product-strategist/SKILL.md](../../product-team/product-strategist/SKILL.md)
- **Competitive Teardown Skill:** [../../product-team/competitive-teardown/SKILL.md](../../product-team/competitive-teardown/SKILL.md)
- **OKR Framework:** [../../product-team/product-strategist/references/okr_framework.md](../../product-team/product-strategist/references/okr_framework.md)
- **Strategy Types:** [../../product-team/product-strategist/references/strategy_types.md](../../product-team/product-strategist/references/strategy_types.md)
- **Product Domain Guide:** [../../product-team/CLAUDE.md](../../product-team/CLAUDE.md)
- **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md)
---
**Last Updated:** March 9, 2026
**Status:** Production Ready
**Version:** 1.0

531
agents/product/cs-ux-researcher.md Normal file
View File

@@ -0,0 +1,531 @@
---
name: cs-ux-researcher
description: UX research agent for research planning, persona generation, journey mapping, and usability test analysis
skills: product-team/ux-researcher-designer, product-team/product-manager-toolkit, product-team/ui-design-system
domain: product
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---
# UX Researcher Agent
## Purpose
The cs-ux-researcher agent is a specialized user experience research agent focused on research planning, persona creation, journey mapping, and usability test analysis. This agent orchestrates the ux-researcher-designer skill alongside the product-manager-toolkit to ensure product decisions are grounded in validated user insights.
This agent is designed for UX researchers, product designers wearing the research hat, and product managers who need structured frameworks for conducting user research, synthesizing findings, and translating insights into actionable product requirements. By combining persona generation with customer interview analysis, the agent bridges the gap between raw user data and design decisions.
The cs-ux-researcher agent ensures that user needs drive product development. It provides methodological rigor for research planning, data-driven persona creation, systematic journey mapping, and structured usability evaluation. The agent works closely with the ui-design-system skill for design handoff and with the product-manager-toolkit for translating research insights into prioritized feature requirements.
## Skill Integration
**Primary Skill:** `../../product-team/ux-researcher-designer/`
### All Orchestrated Skills
| # | Skill | Location | Primary Tool |
|---|-------|----------|-------------|
| 1 | UX Researcher & Designer | `../../product-team/ux-researcher-designer/` | persona_generator.py |
| 2 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | customer_interview_analyzer.py |
| 3 | UI Design System | `../../product-team/ui-design-system/` | design_token_generator.py |
### Python Tools
1. **Persona Generator**
- **Purpose:** Create data-driven user personas from research inputs including demographics, goals, pain points, and behavioral patterns
- **Path:** `../../product-team/ux-researcher-designer/scripts/persona_generator.py`
- **Usage:** `python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json`
- **Features:** Multiple persona generation, behavioral segmentation, needs hierarchy mapping, empathy map creation
- **Use Cases:** Persona development, user segmentation, design alignment, stakeholder communication
2. **Customer Interview Analyzer**
- **Purpose:** NLP-based analysis of interview transcripts to extract pain points, feature requests, themes, and sentiment
- **Path:** `../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py`
- **Usage:** `python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt`
- **Features:** Pain point extraction with severity scoring, feature request identification, jobs-to-be-done patterns, theme clustering, key quote extraction
- **Use Cases:** Interview synthesis, discovery validation, problem prioritization, insight aggregation
3. **Design Token Generator**
- **Purpose:** Generate design tokens for consistent UI implementation across platforms
- **Path:** `../../product-team/ui-design-system/scripts/design_token_generator.py`
- **Usage:** `python ../../product-team/ui-design-system/scripts/design_token_generator.py theme.json`
- **Use Cases:** Research-informed design system updates, accessibility token adjustments
### Knowledge Bases
1. **Persona Methodology**
- **Location:** `../../product-team/ux-researcher-designer/references/persona-methodology.md`
- **Content:** Research-backed persona creation methodology, data collection strategies, validation approaches
- **Use Case:** Methodological guidance for persona projects
2. **Example Personas**
- **Location:** `../../product-team/ux-researcher-designer/references/example-personas.md`
- **Content:** Sample persona documents with demographics, goals, pain points, behaviors, scenarios
- **Use Case:** Persona format reference, team training
3. **Journey Mapping Guide**
- **Location:** `../../product-team/ux-researcher-designer/references/journey-mapping-guide.md`
- **Content:** Customer journey mapping methodology, touchpoint analysis, emotion mapping, opportunity identification
- **Use Case:** Journey map creation, experience design, service design
4. **Usability Testing Frameworks**
- **Location:** `../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md`
- **Content:** Test planning, task design, analysis methods, severity ratings, reporting formats
- **Use Case:** Usability study design, prototype validation, UX evaluation
5. **Component Architecture**
- **Location:** `../../product-team/ui-design-system/references/component-architecture.md`
- **Content:** Component hierarchy, atomic design patterns, composition strategies
- **Use Case:** Research-to-design translation, component recommendations
6. **Developer Handoff**
- **Location:** `../../product-team/ui-design-system/references/developer-handoff.md`
- **Content:** Design-to-dev handoff process, specification formats, asset delivery
- **Use Case:** Translating research findings into implementation specs
### Templates
1. **Research Plan Template**
- **Location:** `../../product-team/ux-researcher-designer/assets/research_plan_template.md`
- **Use Case:** Structuring research studies with methodology, participants, and analysis plan
2. **Design System Documentation Template**
- **Location:** `../../product-team/ui-design-system/assets/design_system_doc_template.md`
- **Use Case:** Documenting research-informed design system decisions
## Workflows
### Workflow 1: Research Plan Creation
**Goal:** Design a rigorous research study that answers specific product questions with appropriate methodology
**Steps:**
1. **Define Research Questions** - Identify what needs to be learned:
- What are the top 3-5 questions stakeholders need answered?
- What do we already know from existing data?
- What assumptions need validation?
- What decisions will this research inform?
2. **Select Methodology** - Choose the right approach:
```bash
# Review usability testing frameworks for method selection
cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md
```
- **Exploratory** (interviews, contextual inquiry): When learning about problem space
- **Evaluative** (usability testing, A/B tests): When validating solutions
- **Generative** (diary studies, card sorting): When discovering new opportunities
- **Quantitative** (surveys, analytics): When measuring scale and significance
3. **Define Participants** - Screen for the right users:
- Target persona(s) to recruit
- Screening criteria (role, experience, usage patterns)
- Sample size justification
- Recruitment channels and incentives
4. **Create Study Materials** - Prepare research instruments:
```bash
# Use the research plan template
cat ../../product-team/ux-researcher-designer/assets/research_plan_template.md
```
- Interview guide or test script
- Task scenarios (for usability tests)
- Consent form and recording permissions
- Analysis framework and coding scheme
5. **Align with Stakeholders** - Get buy-in:
- Share research plan with product and engineering leads
- Invite stakeholders to observe sessions
- Set expectations for timeline and deliverables
- Define how findings will be actioned
**Expected Output:** Complete research plan with questions, methodology, participant criteria, study materials, timeline, and stakeholder alignment
**Time Estimate:** 2-3 days for plan creation
**Example:**
```bash
# Create research plan from template
cp ../../product-team/ux-researcher-designer/assets/research_plan_template.md onboarding-research-plan.md
# Review methodology options
cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md
# Review persona methodology for participant criteria
cat ../../product-team/ux-researcher-designer/references/persona-methodology.md
```
### Workflow 2: Persona Generation
**Goal:** Create data-driven user personas from research data that align product teams around real user needs
**Steps:**
1. **Gather Research Data** - Collect inputs from multiple sources:
- Interview transcripts (analyzed for themes)
- Survey responses (demographic and behavioral data)
- Analytics data (usage patterns, feature adoption)
- Support tickets (common issues, pain points)
- Sales call notes (buyer motivations, objections)
2. **Analyze Interview Data** - Extract structured insights:
```bash
# Analyze each interview transcript
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.json
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.json
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.json
```
3. **Identify Behavioral Segments** - Cluster users by:
- Goals and motivations (what they are trying to achieve)
- Behaviors and workflows (how they work today)
- Pain points and frustrations (what blocks them)
- Technical sophistication (how they interact with tools)
- Decision-making factors (what drives their choices)
4. **Generate Personas** - Create data-backed personas:
```bash
# Generate personas from aggregated research
python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json
```
5. **Validate Personas** - Ensure accuracy:
- Cross-reference with quantitative data (segment sizes)
- Review with customer-facing teams (sales, support)
- Test with stakeholders who interact with users
- Confirm each persona represents a meaningful segment
6. **Socialize Personas** - Make personas actionable:
```bash
# Review example personas for format guidance
cat ../../product-team/ux-researcher-designer/references/example-personas.md
```
- Create one-page persona cards for team walls/wikis
- Present to product, engineering, and design teams
- Map personas to product areas and features
- Reference personas in PRDs and design briefs
**Expected Output:** 3-5 validated user personas with demographics, goals, pain points, behaviors, and scenarios
**Time Estimate:** 1-2 weeks (data collection through socialization)
**Example:**
```bash
# Full persona generation workflow
echo "Persona Generation Workflow"
echo "==========================="
# Step 1: Analyze interviews
for f in interviews/*.txt; do
base=$(basename "$f" .txt)
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights-$base.json"
echo "Analyzed: $f"
done
# Step 2: Review persona methodology
cat ../../product-team/ux-researcher-designer/references/persona-methodology.md
# Step 3: Generate personas
python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json
# Step 4: Review example format
cat ../../product-team/ux-researcher-designer/references/example-personas.md
```
### Workflow 3: Journey Mapping
**Goal:** Map the complete user journey to identify pain points, opportunities, and moments that matter
**Steps:**
1. **Define Journey Scope** - Set boundaries:
- Which persona is this journey for?
- What is the starting trigger?
- What is the end state (success)?
- What timeframe does the journey cover?
2. **Review Journey Mapping Methodology** - Understand the framework:
```bash
cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md
```
3. **Map Journey Stages** - Identify key phases:
- **Awareness:** How users discover the product
- **Consideration:** How users evaluate and compare
- **Onboarding:** First-time setup and activation
- **Regular Use:** Core workflow and daily interactions
- **Growth:** Expanding usage, inviting team, upgrading
- **Advocacy:** Referring others, providing feedback
4. **Document Touchpoints** - For each stage:
- User actions (what they do)
- Channels (where they interact)
- Emotions (how they feel)
- Pain points (what frustrates them)
- Opportunities (how we can improve)
5. **Identify Moments of Truth** - Critical experience points:
- First-time use (aha moment)
- First success (value realization)
- First problem (support experience)
- Upgrade decision (value justification)
- Referral moment (advocacy trigger)
6. **Prioritize Opportunities** - Focus on highest-impact improvements:
```bash
# Prioritize journey improvement opportunities
cat > journey-opportunities.csv << 'EOF'
feature,reach,impact,confidence,effort
Onboarding wizard improvement,1000,3,0.9,3
First-success celebration,800,2,0.7,1
Self-service help in context,600,2,0.8,2
Upgrade prompt optimization,400,3,0.6,2
EOF
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv
```
**Expected Output:** Visual journey map with stages, touchpoints, emotions, pain points, and prioritized improvement opportunities
**Time Estimate:** 1-2 weeks for research-backed journey map
**Example:**
```bash
# Journey mapping workflow
echo "Journey Mapping - Onboarding Flow"
echo "=================================="
# Review journey mapping methodology
cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md
# Analyze relevant interview transcripts for journey insights
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-01.txt
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-02.txt
# Prioritize improvement opportunities
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv
```
### Workflow 4: Usability Test Analysis
**Goal:** Conduct and analyze usability tests to evaluate design solutions and identify critical UX issues
**Steps:**
1. **Plan the Test** - Design the study:
```bash
# Review usability testing frameworks
cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md
```
- Define test objectives (what decisions will this inform)
- Select test type (moderated/unmoderated, remote/in-person)
- Write task scenarios (realistic, goal-oriented)
- Set success criteria per task (completion, time, errors)
2. **Prepare Materials** - Set up the test:
- Prototype or staging environment ready
- Test script with introduction, tasks, and debrief questions
- Recording tools configured
- Note-taking template for observers
- Use research plan template for documentation:
```bash
cat ../../product-team/ux-researcher-designer/assets/research_plan_template.md
```
3. **Conduct Sessions** - Run 5-8 sessions:
- Follow consistent script for each participant
- Use think-aloud protocol
- Note task completion, errors, and verbal feedback
- Capture quotes and emotional reactions
- Debrief after each session
4. **Analyze Results** - Synthesize findings:
- Calculate task success rates
- Measure time-on-task per scenario
- Categorize usability issues by severity:
- **Critical:** Prevents task completion
- **Major:** Causes significant difficulty or errors
- **Minor:** Creates confusion but user recovers
- **Cosmetic:** Aesthetic or minor friction
- Identify patterns across participants
5. **Analyze Verbal Feedback** - Extract qualitative insights:
```bash
# Analyze session transcripts for themes
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-01.txt
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-02.txt
```
6. **Create Report and Recommendations** - Deliver findings:
- Executive summary (key findings in 3-5 bullets)
- Task-by-task results with evidence
- Prioritized issue list with severity
- Recommended design changes
- Highlight reel of key moments (video clips)
7. **Inform Design Iteration** - Close the loop:
- Review findings with design team
- Map issues to components in design system:
```bash
cat ../../product-team/ui-design-system/references/component-architecture.md
```
- Create Jira tickets for each issue
- Plan re-test for critical issues after fixes
**Expected Output:** Usability test report with task metrics, severity-rated issues, recommendations, and design iteration plan
**Time Estimate:** 2-3 weeks (planning through report delivery)
**Example:**
```bash
# Usability test analysis workflow
echo "Usability Test Analysis"
echo "======================="
# Review frameworks
cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md
# Analyze each session transcript
for i in 1 2 3 4 5; do
echo "Session $i Analysis:"
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "usability-session-0$i.txt"
echo ""
done
# Review component architecture for design recommendations
cat ../../product-team/ui-design-system/references/component-architecture.md
```
## Integration Examples
### Example 1: Discovery Sprint Research
```bash
#!/bin/bash
# discovery-research.sh - 2-week discovery sprint
echo "Discovery Sprint Research"
echo "========================="
# Week 1: Research execution
echo ""
echo "Week 1: Conduct & Analyze Interviews"
echo "-------------------------------------"
# Analyze all interview transcripts
for f in discovery-interviews/*.txt; do
base=$(basename "$f" .txt)
echo "Analyzing: $base"
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights/$base.json"
done
# Week 2: Synthesis
echo ""
echo "Week 2: Generate Personas & Journey Map"
echo "----------------------------------------"
# Generate personas from aggregated data
python ../../product-team/ux-researcher-designer/scripts/persona_generator.py aggregated-research.json
# Reference journey mapping guide
echo "Journey mapping guide: ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md"
```
### Example 2: Research Repository Update
```bash
#!/bin/bash
# research-update.sh - Monthly research insights update
echo "Research Repository Update - $(date +%Y-%m-%d)"
echo "================================================"
# Process new interviews
echo ""
echo "New Interview Analysis:"
for f in new-interviews/*.txt; do
python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f"
echo "---"
done
# Review and refresh personas
echo ""
echo "Persona Review:"
echo "Current personas: ../../product-team/ux-researcher-designer/references/example-personas.md"
echo "Methodology: ../../product-team/ux-researcher-designer/references/persona-methodology.md"
```
### Example 3: Design Handoff with Research Context
```bash
#!/bin/bash
# research-handoff.sh - Prepare research context for design team
echo "Research Handoff Package"
echo "========================"
# Persona context
echo ""
echo "1. Active Personas:"
cat ../../product-team/ux-researcher-designer/references/example-personas.md | head -30
# Journey context
echo ""
echo "2. Journey Map Reference:"
echo "See: ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md"
# Design system alignment
echo ""
echo "3. Component Architecture:"
echo "See: ../../product-team/ui-design-system/references/component-architecture.md"
# Developer handoff process
echo ""
echo "4. Handoff Process:"
echo "See: ../../product-team/ui-design-system/references/developer-handoff.md"
```
## Success Metrics
**Research Quality:**
- **Study Rigor:** 100% of studies have documented research plan with methodology justification
- **Participant Quality:** >90% of participants match screening criteria
- **Insight Actionability:** >80% of research findings result in backlog items or design changes
- **Stakeholder Engagement:** >2 stakeholders observe each research session
**Persona Effectiveness:**
- **Team Adoption:** >80% of PRDs reference a specific persona
- **Validation Rate:** Personas validated with quantitative data (segment sizes, usage patterns)
- **Refresh Cadence:** Personas reviewed and updated at least semi-annually
- **Decision Influence:** Personas cited in >50% of product design decisions
**Usability Impact:**
- **Issue Detection:** 5+ unique usability issues identified per study
- **Fix Rate:** >70% of critical/major issues resolved within 2 sprints
- **Task Success:** Average task success rate improves by >15% after design iteration
- **User Satisfaction:** SUS score improves by >5 points after research-informed redesign
**Business Impact:**
- **Customer Satisfaction:** NPS improvement correlated with research-informed changes
- **Onboarding Conversion:** First-time user activation rate improvement
- **Support Ticket Reduction:** Fewer UX-related support requests
- **Feature Adoption:** Research-informed features show >20% higher adoption rates
## Related Agents
- [cs-product-manager](cs-product-manager.md) - Product management lifecycle, interview analysis, PRD development
- [cs-agile-product-owner](cs-agile-product-owner.md) - Translating research findings into user stories
- [cs-product-strategist](cs-product-strategist.md) - Strategic research to validate product vision and positioning
- UI Design System - Design handoff and component recommendations (see `../../product-team/ui-design-system/`)
## References
- **Primary Skill:** [../../product-team/ux-researcher-designer/SKILL.md](../../product-team/ux-researcher-designer/SKILL.md)
- **Interview Analyzer:** [../../product-team/product-manager-toolkit/SKILL.md](../../product-team/product-manager-toolkit/SKILL.md)
- **Persona Methodology:** [../../product-team/ux-researcher-designer/references/persona-methodology.md](../../product-team/ux-researcher-designer/references/persona-methodology.md)
- **Journey Mapping Guide:** [../../product-team/ux-researcher-designer/references/journey-mapping-guide.md](../../product-team/ux-researcher-designer/references/journey-mapping-guide.md)
- **Usability Testing:** [../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md](../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md)
- **Design System:** [../../product-team/ui-design-system/SKILL.md](../../product-team/ui-design-system/SKILL.md)
- **Product Domain Guide:** [../../product-team/CLAUDE.md](../../product-team/CLAUDE.md)
- **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md)
---
**Last Updated:** March 9, 2026
**Status:** Production Ready
**Version:** 1.0

539
agents/project-management/cs-project-manager.md
View File

@@ -1,54 +1,515 @@
--- ---
name: cs-project-manager name: cs-project-manager
description: Project Manager agent for sprint planning, Jira/Confluence workflows, Scrum ceremonies, and stakeholder reporting. Orchestrates project-management skills. Spawn when users need sprint planning, Jira configuration, workflow design, retrospectives, or project status dashboards. description: Project Manager agent for sprint planning, Jira/Confluence workflows, Scrum ceremonies, and stakeholder reporting. Orchestrates project-management skills.
skills: project-management
domain: pm
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
--- ---
# cs-project-manager # Project Manager Agent
## Role & Expertise ## Purpose
Experienced PM covering agile delivery, Atlassian administration, and stakeholder management. Runs sprints, designs workflows, creates templates, and generates reports. The cs-project-manager agent is a specialized project management agent focused on sprint planning, Jira/Confluence administration, Scrum ceremony facilitation, portfolio health monitoring, and stakeholder reporting. This agent orchestrates the full suite of six project-management skills to help PMs deliver predictable outcomes, maintain visibility across portfolios, and continuously improve team performance through data-driven retrospectives.
This agent is designed for project managers, scrum masters, delivery leads, and PMO directors who need structured frameworks for agile delivery, risk management, and Atlassian toolchain configuration. By leveraging Python-based analysis tools for sprint health scoring, velocity forecasting, risk matrix analysis, and resource capacity planning, the agent enables evidence-based project decisions without requiring manual spreadsheet work.
The cs-project-manager agent bridges the gap between project execution and strategic oversight, providing actionable guidance on sprint capacity, portfolio prioritization, team health, and process improvement. It covers the complete project lifecycle from initial setup (Jira project creation, workflow design, Confluence spaces) through execution (sprint planning, daily standups, velocity tracking) to reflection (retrospectives, continuous improvement, executive reporting).
## Skill Integration ## Skill Integration
- `project-management/jira-expert` — JQL, workflows, automation, dashboards ### Senior PM
- `project-management/confluence-expert` — Documentation, templates, knowledge bases
- `project-management/scrum-master` — Sprint health, velocity, retrospectives
- `project-management/senior-pm` — Risk analysis, resource optimization, portfolio management
- `project-management/atlassian-admin` — User provisioning, permissions, integrations
- `project-management/atlassian-templates` — Blueprints, custom layouts, reusable components
## Core Workflows **Skill Location:** `../../project-management/senior-pm/`
### 1. Sprint Planning **Python Tools:**
1. Review backlog via `jira-expert` (JQL for upcoming items)
2. Estimate capacity using `scrum-master` velocity tools
3. Prioritize with WSJF via `senior-pm`
4. Create sprint in Jira with goals and scope
5. Document sprint plan in Confluence via `confluence-expert`
### 2. Jira Workflow Design 1. **Project Health Dashboard**
1. Map team process to workflow states - **Purpose:** Generate portfolio-level health dashboard with RAG status across all active projects
2. Design transitions, conditions, validators (ref: `jira-expert/references/WORKFLOWS.md`) - **Path:** `../../project-management/senior-pm/scripts/project_health_dashboard.py`
3. Set up automation rules (ref: `jira-expert/references/AUTOMATION.md`) - **Usage:** `python ../../project-management/senior-pm/scripts/project_health_dashboard.py sample_project_data.json`
4. Create dashboards for visibility - **Features:** Schedule variance, budget tracking, risk exposure, milestone status, RAG indicators
5. Test with pilot team, iterate
### 3. Retrospective Facilitation 2. **Risk Matrix Analyzer**
1. Gather sprint metrics via `scrum-master` scripts - **Purpose:** Quantitative risk analysis with probability-impact matrices and Expected Monetary Value (EMV)
2. Calculate sprint health score - **Path:** `../../project-management/senior-pm/scripts/risk_matrix_analyzer.py`
3. Run retro format (Start/Stop/Continue, 4Ls, or Sailboat) - **Usage:** `python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py risks.json`
4. Document action items in Confluence - **Features:** Risk scoring, heat map generation, mitigation tracking, EMV calculation
5. Create Jira tickets for improvement items
### 4. Stakeholder Reporting 3. **Resource Capacity Planner**
1. Pull project metrics via `senior-pm` scripts - **Purpose:** Team resource allocation and capacity forecasting across sprints and projects
2. Generate risk assessment with EMV analysis - **Path:** `../../project-management/senior-pm/scripts/resource_capacity_planner.py`
3. Create executive dashboard in Confluence - **Usage:** `python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json`
4. Schedule automated Jira reports - **Features:** Utilization analysis, over-allocation detection, capacity forecasting, cross-project balancing
## Output Standards **Knowledge Bases:**
- Sprint plans → Confluence page with Jira macro embedding
- Reports → structured with RAG status, risks, actions - `../../project-management/senior-pm/references/portfolio-prioritization-models.md` -- WSJF, MoSCoW, Cost of Delay, portfolio scoring frameworks
- Workflows → documented with transition diagrams - `../../project-management/senior-pm/references/risk-management-framework.md` -- Risk identification, qualitative/quantitative analysis, response strategies
- All time estimates include confidence ranges - `../../project-management/senior-pm/references/portfolio-kpis.md` -- KPI definitions, tracking cadences, executive reporting metrics
**Templates:**
- `../../project-management/senior-pm/assets/executive_report_template.md` -- Executive status report with RAG, risks, decisions needed
- `../../project-management/senior-pm/assets/project_charter_template.md` -- Project charter with scope, objectives, constraints, stakeholders
- `../../project-management/senior-pm/assets/raci_matrix_template.md` -- Responsibility assignment matrix for cross-functional teams
### Scrum Master
**Skill Location:** `../../project-management/scrum-master/`
**Python Tools:**
1. **Sprint Health Scorer**
- **Purpose:** Quantitative sprint health assessment across scope, velocity, quality, and team morale
- **Path:** `../../project-management/scrum-master/scripts/sprint_health_scorer.py`
- **Usage:** `python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sample_sprint_data.json`
- **Features:** Multi-dimensional scoring (0-100), trend analysis, health indicators, actionable recommendations
2. **Velocity Analyzer**
- **Purpose:** Historical velocity analysis with forecasting and confidence intervals
- **Path:** `../../project-management/scrum-master/scripts/velocity_analyzer.py`
- **Usage:** `python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json`
- **Features:** Rolling averages, standard deviation, sprint-over-sprint trends, capacity prediction
3. **Retrospective Analyzer**
- **Purpose:** Structured retrospective analysis with action item tracking and theme extraction
- **Path:** `../../project-management/scrum-master/scripts/retrospective_analyzer.py`
- **Usage:** `python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json`
- **Features:** Theme clustering, sentiment analysis, action item extraction, trend tracking across sprints
**Knowledge Bases:**
- `../../project-management/scrum-master/references/retro-formats.md` -- Start/Stop/Continue, 4Ls, Sailboat, Mad/Sad/Glad, Starfish formats
- `../../project-management/scrum-master/references/team-dynamics-framework.md` -- Tuckman stages, psychological safety, conflict resolution
- `../../project-management/scrum-master/references/velocity-forecasting-guide.md` -- Monte Carlo simulation, confidence ranges, capacity planning
**Templates:**
- `../../project-management/scrum-master/assets/sprint_report_template.md` -- Sprint review report with burndown, velocity, demo notes
- `../../project-management/scrum-master/assets/team_health_check_template.md` -- Spotify-style team health check across 8 dimensions
### Jira Expert
**Skill Location:** `../../project-management/jira-expert/`
**Knowledge Bases:**
- `../../project-management/jira-expert/references/jql-examples.md` -- JQL query patterns for backlog grooming, sprint reporting, SLA tracking
- `../../project-management/jira-expert/references/automation-examples.md` -- Jira automation rule templates for common workflows
- `../../project-management/jira-expert/references/AUTOMATION.md` -- Comprehensive automation guide with triggers, conditions, actions
- `../../project-management/jira-expert/references/WORKFLOWS.md` -- Workflow design patterns, transition rules, validators, post-functions
### Confluence Expert
**Skill Location:** `../../project-management/confluence-expert/`
**Knowledge Bases:**
- `../../project-management/confluence-expert/references/templates.md` -- Page templates for sprint plans, meeting notes, decision logs, architecture docs
### Atlassian Admin
**Skill Location:** `../../project-management/atlassian-admin/`
Covers user provisioning, permission schemes, project configuration, and integration setup. No scripts or references yet -- relies on SKILL.md workflows.
### Atlassian Templates
**Skill Location:** `../../project-management/atlassian-templates/`
Covers blueprint creation, custom page layouts, and reusable Confluence/Jira components. No scripts or references yet -- relies on SKILL.md workflows.
## Workflows
### Workflow 1: Sprint Planning and Execution
**Goal:** Plan a sprint with data-driven capacity, clear backlog priorities, and documented sprint goals published to Confluence.
**Steps:**
1. **Analyze Velocity History** - Review past sprint performance to set realistic capacity:
```bash
python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json
```
- Review rolling average velocity and standard deviation
- Identify trends (accelerating, decelerating, stable)
- Set sprint capacity at 80% of average velocity (buffer for unknowns)
2. **Query Backlog via JQL** - Use jira-expert JQL patterns to pull prioritized candidates:
- Reference: `../../project-management/jira-expert/references/jql-examples.md`
- Filter by priority, story points estimated, team assignment
- Identify blocked items, external dependencies, carry-overs from previous sprint
3. **Check Resource Availability** - Verify team capacity for the sprint window:
```bash
python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json
```
- Account for PTO, holidays, shared resources
- Flag over-allocated team members
- Adjust sprint capacity based on actual availability
4. **Select Sprint Backlog** - Commit items within capacity:
- Apply WSJF or priority-based selection (ref: `../../project-management/senior-pm/references/portfolio-prioritization-models.md`)
- Ensure sprint goal alignment -- every item should contribute to 1-2 goals
- Include 10-15% capacity for bug fixes and operational work
5. **Document Sprint Plan** - Create Confluence sprint plan page:
- Use template from `../../project-management/confluence-expert/references/templates.md`
- Include sprint goal, committed stories, capacity breakdown, risks
- Link to Jira sprint board for live tracking
6. **Set Up Sprint Tracking** - Configure dashboards and automation:
- Create burndown/burnup dashboard (ref: `../../project-management/jira-expert/references/AUTOMATION.md`)
- Set up daily standup reminder automation
- Configure sprint scope change alerts
**Expected Output:** Sprint plan Confluence page with committed backlog, velocity-based capacity justification, team availability matrix, and linked Jira sprint board.
**Time Estimate:** 2-4 hours for complete sprint planning session (including backlog refinement)
**Example:**
```bash
# Full sprint planning workflow
python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_report.txt
python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json > capacity_report.txt
cat velocity_report.txt
cat capacity_report.txt
# Use velocity average and capacity data to commit sprint items
```
### Workflow 2: Portfolio Health Review
**Goal:** Generate an executive-level portfolio health dashboard with RAG status, risk exposure, and resource utilization across all active projects.
**Steps:**
1. **Collect Project Data** - Gather metrics from all active projects:
- Schedule performance (planned vs actual milestones)
- Budget consumption (actual vs forecast)
- Scope changes (CRs approved, backlog growth)
- Quality metrics (defect rates, test coverage)
2. **Generate Health Dashboard** - Run project health analysis:
```bash
python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_data.json
```
- Review per-project RAG status (Red/Amber/Green)
- Identify projects requiring intervention
- Track schedule and budget variance percentages
3. **Analyze Risk Exposure** - Quantify portfolio-level risk:
```bash
python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json
```
- Calculate EMV for each risk
- Identify top-10 risks by exposure
- Review mitigation plan progress
- Flag risks with no assigned owner
4. **Review Resource Utilization** - Check cross-project allocation:
```bash
python ../../project-management/senior-pm/scripts/resource_capacity_planner.py all_teams.json
```
- Identify over-allocated individuals (>100% utilization)
- Find under-utilized capacity for rebalancing
- Forecast resource needs for next quarter
5. **Prepare Executive Report** - Assemble findings into report:
- Use template: `../../project-management/senior-pm/assets/executive_report_template.md`
- Include RAG summary, risk heatmap, resource utilization chart
- Highlight decisions needed from leadership
- Provide recommendations with supporting data
6. **Publish to Confluence** - Create executive dashboard page:
- Reference KPI definitions from `../../project-management/senior-pm/references/portfolio-kpis.md`
- Embed Jira macros for live data
- Set up weekly refresh cadence
**Expected Output:** Executive portfolio dashboard with per-project RAG status, top risks with EMV, resource utilization heatmap, and leadership decision requests.
**Time Estimate:** 3-5 hours for complete portfolio review (monthly cadence recommended)
**Example:**
```bash
# Portfolio health review automation
python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_data.json > health_dashboard.txt
python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json > risk_report.txt
python ../../project-management/senior-pm/scripts/resource_capacity_planner.py all_teams.json > resource_report.txt
cat health_dashboard.txt
cat risk_report.txt
cat resource_report.txt
```
### Workflow 3: Retrospective and Continuous Improvement
**Goal:** Facilitate a structured retrospective, extract actionable themes, track improvement metrics, and ensure action items drive measurable change.
**Steps:**
1. **Gather Sprint Metrics** - Collect quantitative data before the retro:
```bash
python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_data.json
```
- Review sprint health score (0-100)
- Identify scoring dimensions that dropped (scope, velocity, quality, morale)
- Compare against previous sprint scores for trend analysis
2. **Select Retro Format** - Choose format based on team needs:
- Reference: `../../project-management/scrum-master/references/retro-formats.md`
- **Start/Stop/Continue**: General-purpose, good for new teams
- **4Ls (Liked/Learned/Lacked/Longed For)**: Focuses on learning and growth
- **Sailboat**: Visual metaphor for anchors (blockers) and wind (accelerators)
- **Mad/Sad/Glad**: Emotion-focused, good for addressing team morale
- **Starfish**: Five categories for nuanced feedback
3. **Facilitate Retrospective** - Run the session:
- Present sprint metrics as context (not judgment)
- Time-box each section (5 min brainstorm, 10 min discuss, 5 min vote)
- Use dot voting to prioritize discussion topics
- Reference team dynamics from `../../project-management/scrum-master/references/team-dynamics-framework.md`
4. **Analyze Retro Output** - Extract structured insights:
```bash
python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json
```
- Identify recurring themes across sprints
- Cluster related items into improvement areas
- Track action item completion from previous retros
5. **Create Action Items** - Convert insights to trackable work:
- Limit to 2-3 action items per sprint (avoid overcommitment)
- Assign clear owners and due dates
- Create Jira tickets for process improvements
- Add action items to next sprint backlog
6. **Document in Confluence** - Publish retro summary:
- Use sprint report template: `../../project-management/scrum-master/assets/sprint_report_template.md`
- Include sprint health score, retro themes, action items, metrics trends
- Link to previous retro pages for longitudinal tracking
7. **Track Improvement Over Time** - Measure continuous improvement:
- Compare sprint health scores quarter-over-quarter
- Track action item completion rate (target: >80%)
- Monitor velocity stability as proxy for process maturity
**Expected Output:** Retro summary with prioritized themes, 2-3 owned action items with Jira tickets, sprint health trend chart, and Confluence documentation.
**Time Estimate:** 1.5-2 hours (30 min prep + 60 min retro + 30 min documentation)
**Example:**
```bash
# Pre-retro data collection
python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_data.json > health_score.txt
python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_trend.txt
cat health_score.txt
# Use health score insights to guide retro discussion
python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json > retro_analysis.txt
cat retro_analysis.txt
```
### Workflow 4: Jira/Confluence Setup for New Teams
**Goal:** Stand up a complete Atlassian environment for a new team including Jira project, workflows, automation, Confluence space, and templates.
**Steps:**
1. **Define Team Process** - Map the team's delivery methodology:
- Scrum vs Kanban vs Scrumban
- Issue types needed (Epic, Story, Task, Bug, Spike)
- Custom fields required (team, component, environment)
- Workflow states matching actual process
2. **Create Jira Project** - Set up project structure:
- Select project template (Scrum board, Kanban board, Company-managed)
- Configure issue type scheme with required types
- Set up components and versions
- Define priority scheme and SLA targets
3. **Design Workflows** - Build workflows matching team process:
- Reference: `../../project-management/jira-expert/references/WORKFLOWS.md`
- Map states: Backlog > Ready > In Progress > Review > QA > Done
- Add transitions with conditions (e.g., assignee required for In Progress)
- Configure validators (e.g., story points required before Done)
- Set up post-functions (e.g., auto-assign reviewer, notify channel)
4. **Configure Automation** - Set up time-saving automation rules:
- Reference: `../../project-management/jira-expert/references/AUTOMATION.md`
- Examples from: `../../project-management/jira-expert/references/automation-examples.md`
- Auto-transition: Move to In Progress when branch created
- Auto-assign: Rotate assignments based on workload
- Notifications: Slack alerts for blocked items, SLA breaches
- Cleanup: Auto-close stale items after 30 days
5. **Set Up Confluence Space** - Create team knowledge base:
- Reference: `../../project-management/confluence-expert/references/templates.md`
- Create space with standard page hierarchy:
- Home (team overview, quick links)
- Sprint Plans (per-sprint documentation)
- Meeting Notes (standup, planning, retro)
- Decision Log (ADRs, trade-off decisions)
- Runbooks (operational procedures)
- Link Confluence space to Jira project
6. **Create Dashboards** - Build visibility for team and stakeholders:
- Sprint board with swimlanes by assignee
- Burndown/burnup chart gadget
- Velocity chart for historical tracking
- SLA compliance tracker
- Use JQL patterns from `../../project-management/jira-expert/references/jql-examples.md`
7. **Onboard Team** - Walk team through the setup:
- Document workflow rules and why they exist
- Create quick-reference guide for common Jira operations
- Run a pilot sprint to validate configuration
- Iterate on feedback within first 2 sprints
**Expected Output:** Fully configured Jira project with custom workflows and automation, Confluence space with page hierarchy and templates, team dashboards, and onboarding documentation.
**Time Estimate:** 1-2 days for complete environment setup (excluding pilot sprint)
## Integration Examples
### Example 1: Weekly Project Status Report
```bash
#!/bin/bash
# weekly-status.sh - Automated weekly project status generation
echo "Weekly Project Status - $(date +%Y-%m-%d)"
echo "============================================"
# Sprint health assessment
echo ""
echo "Sprint Health:"
python ../../project-management/scrum-master/scripts/sprint_health_scorer.py current_sprint.json
# Velocity trend
echo ""
echo "Velocity Trend:"
python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json
# Risk exposure
echo ""
echo "Active Risks:"
python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py active_risks.json
# Resource utilization
echo ""
echo "Team Capacity:"
python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json
```
### Example 2: Sprint Retrospective Pipeline
```bash
#!/bin/bash
# retro-pipeline.sh - End-of-sprint analysis pipeline
SPRINT_NUM=$1
echo "Sprint $SPRINT_NUM Retrospective Pipeline"
echo "=========================================="
# Step 1: Score sprint health
echo ""
echo "1. Sprint Health Score:"
python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_${SPRINT_NUM}.json > sprint_health.txt
cat sprint_health.txt
# Step 2: Analyze velocity trend
echo ""
echo "2. Velocity Analysis:"
python ../../project-management/scrum-master/scripts/velocity_analyzer.py velocity_history.json > velocity.txt
cat velocity.txt
# Step 3: Process retro notes
echo ""
echo "3. Retrospective Themes:"
python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_sprint_${SPRINT_NUM}.json > retro_analysis.txt
cat retro_analysis.txt
echo ""
echo "Pipeline complete. Review outputs above for retro facilitation."
```
### Example 3: Portfolio Dashboard Generation
```bash
#!/bin/bash
# portfolio-dashboard.sh - Monthly executive portfolio review
MONTH=$(date +%Y-%m)
echo "Portfolio Dashboard - $MONTH"
echo "================================"
# Project health across portfolio
echo ""
echo "Project Health (All Active):"
python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_$MONTH.json > dashboard.txt
cat dashboard.txt
# Risk heatmap
echo ""
echo "Risk Exposure Summary:"
python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py risks_$MONTH.json > risks.txt
cat risks.txt
# Resource forecast
echo ""
echo "Resource Utilization:"
python ../../project-management/senior-pm/scripts/resource_capacity_planner.py resources_$MONTH.json > capacity.txt
cat capacity.txt
echo ""
echo "Dashboard generated. Use executive_report_template.md to assemble final report."
echo "Template: ../../project-management/senior-pm/assets/executive_report_template.md"
```
## Success Metrics
**Sprint Delivery:**
- **Velocity Stability:** Standard deviation <15% of average velocity over 6 sprints
- **Sprint Goal Achievement:** >85% of sprint goals fully met
- **Scope Change Rate:** <10% of committed stories changed mid-sprint
- **Carry-Over Rate:** <5% of committed stories carry over to next sprint
**Portfolio Health:**
- **On-Time Delivery:** >80% of milestones hit within 1 week of target
- **Budget Variance:** <10% deviation from approved budget
- **Risk Mitigation:** >90% of identified risks have assigned owners and active mitigation plans
- **Resource Utilization:** 75-85% utilization (avoiding burnout while maximizing throughput)
**Process Improvement:**
- **Retro Action Completion:** >80% of action items completed within 2 sprints
- **Sprint Health Trend:** Positive quarter-over-quarter sprint health score trend
- **Cycle Time Reduction:** 15%+ reduction in average story cycle time over 6 months
- **Team Satisfaction:** Health check scores stable or improving across all dimensions
**Stakeholder Communication:**
- **Report Cadence:** 100% on-time delivery of weekly/monthly status reports
- **Decision Turnaround:** <3 days from escalation to leadership decision
- **Stakeholder Confidence:** >90% satisfaction in quarterly PM effectiveness surveys
- **Transparency:** All project data accessible via self-service dashboards
## Related Agents
- [cs-product-manager](../product/cs-product-manager.md) -- Product prioritization with RICE, customer discovery, PRD development
- [cs-agile-product-owner](../product/cs-agile-product-owner.md) -- User story generation, backlog management, acceptance criteria (planned)
- [cs-scrum-master](cs-scrum-master.md) -- Dedicated Scrum ceremony facilitation and team coaching (planned)
## References
- **Senior PM Skill:** [../../project-management/senior-pm/SKILL.md](../../project-management/senior-pm/SKILL.md)
- **Scrum Master Skill:** [../../project-management/scrum-master/SKILL.md](../../project-management/scrum-master/SKILL.md)
- **Jira Expert Skill:** [../../project-management/jira-expert/SKILL.md](../../project-management/jira-expert/SKILL.md)
- **Confluence Expert Skill:** [../../project-management/confluence-expert/SKILL.md](../../project-management/confluence-expert/SKILL.md)
- **Atlassian Admin Skill:** [../../project-management/atlassian-admin/SKILL.md](../../project-management/atlassian-admin/SKILL.md)
- **PM Domain Guide:** [../../project-management/CLAUDE.md](../../project-management/CLAUDE.md)
- **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md)
---
**Last Updated:** March 9, 2026
**Version:** 2.0
**Status:** Production Ready

36
commands/okr.md Normal file
View File

@@ -0,0 +1,36 @@
---
name: okr
description: Generate OKR cascades from company strategy to team objectives. Usage: /okr generate <strategy>
---
# /okr
Generate cascaded OKR frameworks from company-level strategy down to team-level key results.
## Usage
```
/okr generate <strategy> Generate OKR cascade
```
Supported strategies: `growth`, `retention`, `revenue`, `innovation`
## Input Format
Pass a strategy keyword directly. The generator produces company, department, and team-level OKRs aligned to the chosen strategy.
## Examples
```
/okr generate growth
/okr generate retention
/okr generate revenue
/okr generate innovation
/okr generate growth --format json --output okrs.json
```
## Scripts
- `product-team/product-strategist/scripts/okr_cascade_generator.py` — OKR cascade generator
## Skill Reference
> `product-team/product-strategist/SKILL.md`

40
commands/persona.md Normal file
View File

@@ -0,0 +1,40 @@
---
name: persona
description: Generate data-driven user personas for UX research and product design. Usage: /persona generate [options]
---
# /persona
Generate structured user personas with demographics, goals, pain points, and behavioral patterns.
## Usage
```
/persona generate Generate persona (interactive)
/persona generate --output json Generate persona as JSON
```
## Input Format
Interactive mode prompts for product context. Alternatively, provide context inline:
```
/persona generate
> Product: B2B project management tool
> Target: Engineering managers at mid-size companies
> Key problem: Cross-team visibility
```
## Examples
```
/persona generate
/persona generate --output json
/persona generate --output json > persona-eng-manager.json
```
## Scripts
- `product-team/ux-researcher-designer/scripts/persona_generator.py` — Persona generator
## Skill Reference
> `product-team/ux-researcher-designer/SKILL.md`

43
commands/project-health.md Normal file
View File

@@ -0,0 +1,43 @@
---
name: project-health
description: Portfolio health dashboard and risk matrix analysis. Usage: /project-health <dashboard|risk> [options]
---
# /project-health
Generate portfolio health dashboards and risk matrices for project oversight.
## Usage
```
/project-health dashboard <project_data.json> Portfolio health dashboard
/project-health risk <risk_data.json> Risk matrix analysis
```
## Input Format
```json
{
"project_name": "Platform Rewrite",
"schedule": {"planned_end": "2026-06-30", "projected_end": "2026-07-15", "milestones_hit": 4, "milestones_total": 6},
"budget": {"allocated": 500000, "spent": 320000, "forecast": 520000},
"scope": {"features_planned": 40, "features_delivered": 28, "change_requests": 3},
"quality": {"defect_rate": 0.05, "test_coverage": 0.82},
"risks": [{"description": "Key engineer leaving", "probability": 0.3, "impact": 0.8}]
}
```
## Examples
```
/project-health dashboard portfolio-q2.json
/project-health risk risk-register.json
/project-health dashboard portfolio-q2.json --format json --output dashboard.json
```
## Scripts
- `project-management/senior-pm/scripts/project_health_dashboard.py` — Health dashboard
- `project-management/senior-pm/scripts/risk_matrix_analyzer.py` — Risk matrix analyzer
## Skill Reference
> `project-management/senior-pm/SKILL.md`

42
commands/retro.md Normal file
View File

@@ -0,0 +1,42 @@
---
name: retro
description: Analyze sprint retrospectives for patterns and action item tracking. Usage: /retro analyze <retro_data.json>
---
# /retro
Analyze retrospective data for recurring themes, sentiment trends, and action item effectiveness.
## Usage
```
/retro analyze <retro_data.json> Full retrospective analysis
```
## Input Format
```json
{
"sprint_name": "Sprint 24",
"went_well": ["CI pipeline improvements", "Pair programming sessions"],
"improvements": ["Too many meetings", "Flaky integration tests"],
"action_items": [
{"description": "Reduce standup to 10 min", "owner": "SM", "status": "done"},
{"description": "Fix flaky tests", "owner": "QA Lead", "status": "in_progress"}
],
"participants": 8
}
```
## Examples
```
/retro analyze sprint-24-retro.json
/retro analyze sprint-24-retro.json --format json --output retro-report.json
```
## Scripts
- `project-management/scrum-master/scripts/retrospective_analyzer.py` — Retrospective analyzer
## Skill Reference
> `project-management/scrum-master/SKILL.md`

39
commands/rice.md Normal file
View File

@@ -0,0 +1,39 @@
---
name: rice
description: RICE feature prioritization with scoring and capacity planning. Usage: /rice prioritize <features.csv> [options]
---
# /rice
Prioritize features using RICE scoring (Reach, Impact, Confidence, Effort) with optional capacity constraints.
## Usage
```
/rice prioritize <features.csv> Score and rank features
/rice prioritize <features.csv> --capacity 20 Rank with effort capacity limit
```
## Input Format
```csv
feature,reach,impact,confidence,effort
Dark mode,5000,2,0.8,3
API v2,12000,3,0.9,8
SSO integration,3000,2,0.7,5
Mobile app,20000,3,0.5,13
```
## Examples
```
/rice prioritize features.csv
/rice prioritize features.csv --capacity 20
/rice prioritize features.csv --format json --output prioritized.json
```
## Scripts
- `product-team/product-manager-toolkit/scripts/rice_prioritizer.py` — RICE prioritizer
## Skill Reference
> `product-team/product-manager-toolkit/SKILL.md`

43
commands/sprint-health.md Normal file
View File

@@ -0,0 +1,43 @@
---
name: sprint-health
description: Sprint health scoring and velocity analysis for agile teams. Usage: /sprint-health <analyze|velocity> [options]
---
# /sprint-health
Score sprint health across delivery, quality, and team metrics with velocity trend analysis.
## Usage
```
/sprint-health analyze <sprint_data.json> Full sprint health score
/sprint-health velocity <sprint_data.json> Velocity trend analysis
```
## Input Format
```json
{
"sprint_name": "Sprint 24",
"committed_points": 34,
"completed_points": 29,
"stories": {"total": 12, "completed": 10, "carried_over": 2},
"blockers": [{"description": "API dependency", "days_blocked": 3}],
"ceremonies": {"planning": true, "daily": true, "review": true, "retro": true}
}
```
## Examples
```
/sprint-health analyze sprint-24.json
/sprint-health velocity last-6-sprints.json
/sprint-health analyze sprint-24.json --format json --output report.json
```
## Scripts
- `project-management/scrum-master/scripts/sprint_health_scorer.py` — Sprint health scorer
- `project-management/scrum-master/scripts/velocity_analyzer.py` — Velocity analyzer
## Skill Reference
> `project-management/scrum-master/SKILL.md`

44
commands/user-story.md Normal file
View File

@@ -0,0 +1,44 @@
---
name: user-story
description: Generate user stories with acceptance criteria and sprint planning. Usage: /user-story <generate|sprint> [options]
---
# /user-story
Generate structured user stories with acceptance criteria, story points, and sprint capacity planning.
## Usage
```
/user-story generate Generate user stories (interactive)
/user-story sprint <capacity> Plan sprint with story point capacity
```
## Input Format
Interactive mode prompts for feature context. For sprint planning, provide capacity as story points:
```
/user-story generate
> Feature: User authentication
> Persona: Engineering manager
> Epic: Platform Security
/user-story sprint 21
> Stories are ranked by priority and fit within 21-point capacity
```
## Examples
```
/user-story generate
/user-story generate --output json
/user-story sprint 34
/user-story sprint 21 --format json --output sprint-plan.json
```
## Scripts
- `product-team/agile-product-owner/scripts/user_story_generator.py` — User story generator
## Skill Reference
> `product-team/agile-product-owner/SKILL.md`

2
docs/getting-started.md
View File

@@ -99,7 +99,7 @@ AI-augmented development. Optimize for SEO.
## Python Tools ## Python Tools
All 210+ tools use the standard library only — zero pip installs. All 218+ tools use the standard library only — zero pip installs.
```bash ```bash
# Security audit a skill before installing # Security audit a skill before installing

8
docs/index.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Claude Code Skills & Plugins title: Claude Code Skills & Plugins
description: "170 production-ready skills and plugins for Claude Code, OpenAI Codex, and OpenClaw. Reusable expertise bundles for engineering, product, marketing, compliance, and more." description: "177 production-ready skills and plugins for Claude Code, OpenAI Codex, and OpenClaw. Reusable expertise bundles for engineering, product, marketing, compliance, and more."
hide: hide:
- toc - toc
- edit - edit
@@ -14,7 +14,7 @@ hide:
# Claude Code Skills # Claude Code Skills
170 production-ready skills that transform AI coding agents into specialized professionals. 177 production-ready skills that transform AI coding agents into specialized professionals.
{ .hero-subtitle } { .hero-subtitle }
**Claude Code** | **OpenAI Codex** | **OpenClaw** **Claude Code** | **OpenAI Codex** | **OpenClaw**
@@ -27,13 +27,13 @@ hide:
<div class="grid cards" markdown> <div class="grid cards" markdown>
- :material-counter:{ .lg .middle } **170** - :material-counter:{ .lg .middle } **177**
--- ---
Production-ready skills Production-ready skills
- :material-language-python:{ .lg .middle } **210+** - :material-language-python:{ .lg .middle } **218+**
--- ---

50
docs/skills/business-growth/business-growth.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: "Business & Growth Skills"
description: "Business & Growth Skills - Claude Code skill from the Business & Growth domain."
---
# Business & Growth Skills
**Domain:** Business & Growth | **Skill:** `business-growth` | **Source:** [`business-growth/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/business-growth/SKILL.md)
---
# Business & Growth Skills
4 production-ready skills for customer success, sales, and revenue operations.
## Quick Start
### Claude Code
```
/read business-growth/customer-success-manager/SKILL.md
```
### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/business-growth
```
## Skills Overview
| Skill | Folder | Focus |
|-------|--------|-------|
| Customer Success Manager | `customer-success-manager/` | Health scoring, churn prediction, expansion |
| Sales Engineer | `sales-engineer/` | RFP analysis, competitive matrices, PoC planning |
| Revenue Operations | `revenue-operations/` | Pipeline analysis, forecast accuracy, GTM metrics |
| Contract & Proposal Writer | `contract-and-proposal-writer/` | Proposal generation, contract templates |
## Python Tools
9 scripts, all stdlib-only:
```bash
python3 customer-success-manager/scripts/health_score_calculator.py --help
python3 revenue-operations/scripts/pipeline_analyzer.py --help
```
## Rules
- Load only the specific skill SKILL.md you need
- Use Python tools for scoring and metrics, not manual estimates

3
docs/skills/business-growth/index.md
View File

@@ -5,10 +5,11 @@ description: "All Business & Growth skills for Claude Code, OpenAI Codex, and Op
# Business & Growth Skills # Business & Growth Skills
4 skills in this domain. 5 skills in this domain.
| Skill | Description | | Skill | Description |
|-------|-------------| |-------|-------------|
| [Business & Growth Skills](business-growth.md) | `business-growth` |
| [Contract & Proposal Writer](contract-and-proposal-writer.md) | `contract-and-proposal-writer` | | [Contract & Proposal Writer](contract-and-proposal-writer.md) | `contract-and-proposal-writer` |
| [Customer Success Manager](customer-success-manager.md) | `customer-success-manager` | | [Customer Success Manager](customer-success-manager.md) | `customer-success-manager` |
| [Revenue Operations](revenue-operations.md) | `revenue-operations` | | [Revenue Operations](revenue-operations.md) | `revenue-operations` |

83
docs/skills/engineering-team/engineering-team.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: "Engineering Team Skills"
description: "Engineering Team Skills - Claude Code skill from the Engineering - Core domain."
---
# Engineering Team Skills
**Domain:** Engineering - Core | **Skill:** `engineering-team` | **Source:** [`engineering-team/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/SKILL.md)
---
# Engineering Team Skills
23 production-ready engineering skills organized into core engineering, AI/ML/Data, and specialized tools.
## Quick Start
### Claude Code
```
/read engineering-team/senior-fullstack/SKILL.md
```
### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/engineering-team
```
## Skills Overview
### Core Engineering (13 skills)
| Skill | Folder | Focus |
|-------|--------|-------|
| Senior Architect | `senior-architect/` | System design, architecture patterns |
| Senior Frontend | `senior-frontend/` | React, Next.js, TypeScript, Tailwind |
| Senior Backend | `senior-backend/` | API design, database optimization |
| Senior Fullstack | `senior-fullstack/` | Project scaffolding, code quality |
| Senior QA | `senior-qa/` | Test generation, coverage analysis |
| Senior DevOps | `senior-devops/` | CI/CD, infrastructure, containers |
| Senior SecOps | `senior-secops/` | Security operations, vulnerability management |
| Code Reviewer | `code-reviewer/` | PR review, code quality analysis |
| Senior Security | `senior-security/` | Threat modeling, STRIDE, penetration testing |
| AWS Solution Architect | `aws-solution-architect/` | Serverless, CloudFormation, cost optimization |
| MS365 Tenant Manager | `ms365-tenant-manager/` | Microsoft 365 administration |
| TDD Guide | `tdd-guide/` | Test-driven development workflows |
| Tech Stack Evaluator | `tech-stack-evaluator/` | Technology comparison, TCO analysis |
### AI/ML/Data (5 skills)
| Skill | Folder | Focus |
|-------|--------|-------|
| Senior Data Scientist | `senior-data-scientist/` | Statistical modeling, experimentation |
| Senior Data Engineer | `senior-data-engineer/` | Pipelines, ETL, data quality |
| Senior ML Engineer | `senior-ml-engineer/` | Model deployment, MLOps, LLM integration |
| Senior Prompt Engineer | `senior-prompt-engineer/` | Prompt optimization, RAG, agents |
| Senior Computer Vision | `senior-computer-vision/` | Object detection, segmentation |
### Specialized Tools (5 skills)
| Skill | Folder | Focus |
|-------|--------|-------|
| Playwright Pro | `playwright-pro/` | E2E testing (9 sub-skills) |
| Self-Improving Agent | `self-improving-agent/` | Memory curation (5 sub-skills) |
| Stripe Integration | `stripe-integration-expert/` | Payment integration, webhooks |
| Incident Commander | `incident-commander/` | Incident response workflows |
| Email Template Builder | `email-template-builder/` | HTML email generation |
## Python Tools
30+ scripts, all stdlib-only. Run directly:
```bash
python3 <skill>/scripts/<tool>.py --help
```
No pip install needed. Scripts include embedded samples for demo mode.
## Rules
- Load only the specific skill SKILL.md you need — don't bulk-load all 23
- Use Python tools for analysis and scaffolding, not manual judgment
- Check CLAUDE.md for tool usage examples and workflows

3
docs/skills/engineering-team/index.md
View File

@@ -5,13 +5,14 @@ description: "All Engineering - Core skills for Claude Code, OpenAI Codex, and O
# Engineering - Core Skills # Engineering - Core Skills
37 skills in this domain. 38 skills in this domain.
| Skill | Description | | Skill | Description |
|-------|-------------| |-------|-------------|
| [AWS Solution Architect](aws-solution-architect.md) | `aws-solution-architect` | | [AWS Solution Architect](aws-solution-architect.md) | `aws-solution-architect` |
| [Code Reviewer](code-reviewer.md) | `code-reviewer` | | [Code Reviewer](code-reviewer.md) | `code-reviewer` |
| [Email Template Builder](email-template-builder.md) | `email-template-builder` | | [Email Template Builder](email-template-builder.md) | `email-template-builder` |
| [Engineering Team Skills](engineering-team.md) | `engineering-team` |
| [Incident Commander Skill](incident-commander.md) | `incident-commander` | | [Incident Commander Skill](incident-commander.md) | `incident-commander` |
| [Microsoft 365 Tenant Manager](ms365-tenant-manager.md) | `ms365-tenant-manager` | | [Microsoft 365 Tenant Manager](ms365-tenant-manager.md) | `ms365-tenant-manager` |
| [Playwright Pro](playwright-pro.md) | `playwright-pro` | | [Playwright Pro](playwright-pro.md) | `playwright-pro` |

62
docs/skills/engineering/engineering.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: "Engineering Advanced Skills (POWERFUL Tier)"
description: "Engineering Advanced Skills (POWERFUL Tier) - Claude Code skill from the Engineering - POWERFUL domain."
---
# Engineering Advanced Skills (POWERFUL Tier)
**Domain:** Engineering - POWERFUL | **Skill:** `engineering` | **Source:** [`engineering/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/SKILL.md)
---
# Engineering Advanced Skills (POWERFUL Tier)
25 advanced engineering skills for complex architecture, automation, and platform operations.
## Quick Start
### Claude Code
```
/read engineering/agent-designer/SKILL.md
```
### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/engineering
```
## Skills Overview
| Skill | Folder | Focus |
|-------|--------|-------|
| Agent Designer | `agent-designer/` | Multi-agent architecture patterns |
| Agent Workflow Designer | `agent-workflow-designer/` | Workflow orchestration |
| API Design Reviewer | `api-design-reviewer/` | REST/GraphQL linting, breaking changes |
| API Test Suite Builder | `api-test-suite-builder/` | API test generation |
| Changelog Generator | `changelog-generator/` | Automated changelogs |
| CI/CD Pipeline Builder | `ci-cd-pipeline-builder/` | Pipeline generation |
| Codebase Onboarding | `codebase-onboarding/` | New dev onboarding guides |
| Database Designer | `database-designer/` | Schema design, migrations |
| Database Schema Designer | `database-schema-designer/` | ERD, normalization |
| Dependency Auditor | `dependency-auditor/` | Dependency security scanning |
| Env Secrets Manager | `env-secrets-manager/` | Secrets rotation, vault |
| Git Worktree Manager | `git-worktree-manager/` | Parallel branch workflows |
| Interview System Designer | `interview-system-designer/` | Hiring pipeline design |
| MCP Server Builder | `mcp-server-builder/` | MCP tool creation |
| Migration Architect | `migration-architect/` | System migration planning |
| Monorepo Navigator | `monorepo-navigator/` | Monorepo tooling |
| Observability Designer | `observability-designer/` | SLOs, alerts, dashboards |
| Performance Profiler | `performance-profiler/` | CPU, memory, load profiling |
| PR Review Expert | `pr-review-expert/` | Pull request analysis |
| RAG Architect | `rag-architect/` | RAG system design |
| Release Manager | `release-manager/` | Release orchestration |
| Runbook Generator | `runbook-generator/` | Operational runbooks |
| Skill Security Auditor | `skill-security-auditor/` | Skill vulnerability scanning |
| Skill Tester | `skill-tester/` | Skill quality evaluation |
| Tech Debt Tracker | `tech-debt-tracker/` | Technical debt management |
## Rules
- Load only the specific skill SKILL.md you need
- These are advanced skills — combine with engineering-team/ core skills as needed

3
docs/skills/engineering/index.md
View File

@@ -5,7 +5,7 @@ description: "All Engineering - POWERFUL skills for Claude Code, OpenAI Codex, a
# Engineering - POWERFUL Skills # Engineering - POWERFUL Skills
25 skills in this domain. 26 skills in this domain.
| Skill | Description | | Skill | Description |
|-------|-------------| |-------|-------------|
@@ -19,6 +19,7 @@ description: "All Engineering - POWERFUL skills for Claude Code, OpenAI Codex, a
| [Database Designer - POWERFUL Tier Skill](database-designer.md) | `database-designer` | | [Database Designer - POWERFUL Tier Skill](database-designer.md) | `database-designer` |
| [Database Schema Designer](database-schema-designer.md) | `database-schema-designer` | | [Database Schema Designer](database-schema-designer.md) | `database-schema-designer` |
| [Dependency Auditor](dependency-auditor.md) | `dependency-auditor` | | [Dependency Auditor](dependency-auditor.md) | `dependency-auditor` |
| [Engineering Advanced Skills (POWERFUL Tier)](engineering.md) | `engineering` |
| [Env & Secrets Manager](env-secrets-manager.md) | `env-secrets-manager` | | [Env & Secrets Manager](env-secrets-manager.md) | `env-secrets-manager` |
| [Git Worktree Manager](git-worktree-manager.md) | `git-worktree-manager` | | [Git Worktree Manager](git-worktree-manager.md) | `git-worktree-manager` |
| [Interview System Designer](interview-system-designer.md) | `interview-system-designer` | | [Interview System Designer](interview-system-designer.md) | `interview-system-designer` |

49
docs/skills/finance/finance.md Normal file
View File

@@ -0,0 +1,49 @@
---
title: "Finance Skills"
description: "Finance Skills - Claude Code skill from the Finance domain."
---
# Finance Skills
**Domain:** Finance | **Skill:** `finance` | **Source:** [`finance/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/finance/SKILL.md)
---
# Finance Skills
Production-ready financial analysis skill for strategic decision-making.
## Quick Start
### Claude Code
```
/read finance/financial-analyst/SKILL.md
```
### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/finance
```
## Skills Overview
| Skill | Folder | Focus |
|-------|--------|-------|
| Financial Analyst | `financial-analyst/` | Ratio analysis, DCF, budget variance, forecasting |
## Python Tools
4 scripts, all stdlib-only:
```bash
python3 financial-analyst/scripts/ratio_calculator.py --help
python3 financial-analyst/scripts/dcf_valuation.py --help
python3 financial-analyst/scripts/budget_variance_analyzer.py --help
python3 financial-analyst/scripts/forecast_builder.py --help
```
## Rules
- Load only the specific skill SKILL.md you need
- Always validate financial outputs against source data

3
docs/skills/finance/index.md
View File

@@ -5,8 +5,9 @@ description: "All Finance skills for Claude Code, OpenAI Codex, and OpenClaw."
# Finance Skills # Finance Skills
1 skills in this domain. 2 skills in this domain.
| Skill | Description | | Skill | Description |
|-------|-------------| |-------|-------------|
| [Finance Skills](finance.md) | `finance` |
| [Financial Analyst Skill](financial-analyst.md) | `financial-analyst` | | [Financial Analyst Skill](financial-analyst.md) | `financial-analyst` |

5
docs/skills/product-team/agile-product-owner.md
View File

@@ -383,3 +383,8 @@ Story is complete when:
- [ ] Deployed to staging environment - [ ] Deployed to staging environment
- [ ] Product Owner accepted - [ ] Product Owner accepted
- [ ] No critical bugs remaining - [ ] No critical bugs remaining
## Related Skills
- **Scrum Master** (`project-management/scrum-master/`) — Velocity data and sprint ceremonies complement backlog management
- **Product Manager Toolkit** (`product-team/product-manager-toolkit/`) — RICE prioritization feeds backlog ordering

5
docs/skills/product-team/competitive-teardown.md
View File

@@ -171,3 +171,8 @@ Navigation: global search, keyboard shortcuts, in-app help.
5. **UX Highlights** — What they do better (3 bullets) vs. where we win (3 bullets) 5. **UX Highlights** — What they do better (3 bullets) vs. where we win (3 bullets)
6. **Voice of Customer** — Top 3 review complaints (quoted or paraphrased) 6. **Voice of Customer** — Top 3 review complaints (quoted or paraphrased)
7. **Our Action Plan** — Quick wins, medium-term, strategic priorities; Appendix with raw data 7. **Our Action Plan** — Quick wins, medium-term, strategic priorities; Appendix with raw data
## Related Skills
- **Product Strategist** (`product-team/product-strategist/`) — Competitive insights feed OKR and strategy planning
- **Landing Page Generator** (`product-team/landing-page-generator/`) — Competitive positioning informs landing page messaging

3
docs/skills/product-team/index.md
View File

@@ -5,7 +5,7 @@ description: "All Product skills for Claude Code, OpenAI Codex, and OpenClaw."
# Product Skills # Product Skills
8 skills in this domain. 9 skills in this domain.
| Skill | Description | | Skill | Description |
|-------|-------------| |-------|-------------|
@@ -14,6 +14,7 @@ description: "All Product skills for Claude Code, OpenAI Codex, and OpenClaw."
| [Landing Page Generator](landing-page-generator.md) | `landing-page-generator` | | [Landing Page Generator](landing-page-generator.md) | `landing-page-generator` |
| [Product Manager Toolkit](product-manager-toolkit.md) | `product-manager-toolkit` | | [Product Manager Toolkit](product-manager-toolkit.md) | `product-manager-toolkit` |
| [Product Strategist](product-strategist.md) | `product-strategist` | | [Product Strategist](product-strategist.md) | `product-strategist` |
| [Product Team Skills](product-team.md) | `product-team` |
| [SaaS Scaffolder](saas-scaffolder.md) | `saas-scaffolder` | | [SaaS Scaffolder](saas-scaffolder.md) | `saas-scaffolder` |
| [UI Design System](ui-design-system.md) | `ui-design-system` | | [UI Design System](ui-design-system.md) | `ui-design-system` |
| [UX Researcher & Designer](ux-researcher-designer.md) | `ux-researcher-designer` | | [UX Researcher & Designer](ux-researcher-designer.md) | `ux-researcher-designer` |

5
docs/skills/product-team/product-strategist.md
View File

@@ -227,3 +227,8 @@ See `references/examples/sample_growth_okrs.json` for a complete example.
- Adjust contribution percentages based on team size - Adjust contribution percentages based on team size
- Platform/Infrastructure teams often support all objectives - Platform/Infrastructure teams often support all objectives
- Specialized teams (ML, Data) may only support relevant objectives - Specialized teams (ML, Data) may only support relevant objectives
## Related Skills
- **Senior PM** (`project-management/senior-pm/`) — Portfolio management and risk analysis inform strategic planning
- **Competitive Teardown** (`product-team/competitive-teardown/`) — Competitive intelligence feeds product strategy

54
docs/skills/product-team/product-team.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: "Product Team Skills"
description: "Product Team Skills - Claude Code skill from the Product domain."
---
# Product Team Skills
**Domain:** Product | **Skill:** `product-team` | **Source:** [`product-team/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/SKILL.md)
---
# Product Team Skills
8 production-ready product skills covering product management, UX/UI design, and SaaS development.
## Quick Start
### Claude Code
```
/read product-team/product-manager-toolkit/SKILL.md
```
### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/product-team
```
## Skills Overview
| Skill | Folder | Focus |
|-------|--------|-------|
| Product Manager Toolkit | `product-manager-toolkit/` | RICE prioritization, customer discovery, PRDs |
| Agile Product Owner | `agile-product-owner/` | User stories, sprint planning, backlog |
| Product Strategist | `product-strategist/` | OKR cascades, market analysis, vision |
| UX Researcher Designer | `ux-researcher-designer/` | Personas, journey maps, usability testing |
| UI Design System | `ui-design-system/` | Design tokens, component docs, responsive |
| Competitive Teardown | `competitive-teardown/` | Systematic competitor analysis |
| Landing Page Generator | `landing-page-generator/` | Conversion-optimized pages |
| SaaS Scaffolder | `saas-scaffolder/` | Production SaaS boilerplate |
## Python Tools
9 scripts, all stdlib-only:
```bash
python3 product-manager-toolkit/scripts/rice_prioritizer.py --help
python3 product-strategist/scripts/okr_cascade_generator.py --help
```
## Rules
- Load only the specific skill SKILL.md you need
- Use Python tools for scoring and analysis, not manual judgment

5
docs/skills/product-team/ux-researcher-designer.md
View File

@@ -419,3 +419,8 @@ Detailed reference guides in `references/`:
- [ ] Findings include evidence - [ ] Findings include evidence
- [ ] Recommendations are actionable - [ ] Recommendations are actionable
- [ ] Priorities justified - [ ] Priorities justified
## Related Skills
- **UI Design System** (`product-team/ui-design-system/`) — Research findings inform design system decisions
- **Product Manager Toolkit** (`product-team/product-manager-toolkit/`) — Customer interview analysis complements persona research

5
docs/skills/project-management/confluence-expert.md
View File

@@ -375,3 +375,8 @@ const example = "code here";
- Duplicate content - Duplicate content
- Broken links - Broken links
- Empty spaces - Empty spaces
## Related Skills
- **Jira Expert** (`project-management/jira-expert/`) — Jira issue macros and linking complement Confluence docs
- **Atlassian Templates** (`project-management/atlassian-templates/`) — Template patterns for Confluence content creation

3
docs/skills/project-management/index.md
View File

@@ -5,7 +5,7 @@ description: "All Project Management skills for Claude Code, OpenAI Codex, and O
# Project Management Skills # Project Management Skills
6 skills in this domain. 7 skills in this domain.
| Skill | Description | | Skill | Description |
|-------|-------------| |-------|-------------|
@@ -13,5 +13,6 @@ description: "All Project Management skills for Claude Code, OpenAI Codex, and O
| [Atlassian Template & Files Creator Expert](atlassian-templates.md) | `atlassian-templates` | | [Atlassian Template & Files Creator Expert](atlassian-templates.md) | `atlassian-templates` |
| [Atlassian Confluence Expert](confluence-expert.md) | `confluence-expert` | | [Atlassian Confluence Expert](confluence-expert.md) | `confluence-expert` |
| [Atlassian Jira Expert](jira-expert.md) | `jira-expert` | | [Atlassian Jira Expert](jira-expert.md) | `jira-expert` |
| [Project Management Skills](project-management.md) | `project-management` |
| [Scrum Master Expert](scrum-master.md) | `scrum-master` | | [Scrum Master Expert](scrum-master.md) | `scrum-master` |
| [Senior Project Management Expert](senior-pm.md) | `senior-pm` | | [Senior Project Management Expert](senior-pm.md) | `senior-pm` |

5
docs/skills/project-management/jira-expert.md
View File

@@ -305,3 +305,8 @@ mcp jira create_filter --name "Open Blockers" --jql "priority = Blocker AND stat
- Configure sprint boards for Scrum Master - Configure sprint boards for Scrum Master
- Create documentation pages for Confluence Expert - Create documentation pages for Confluence Expert
- Support template creation for Template Creator - Support template creation for Template Creator
## Related Skills
- **Confluence Expert** (`project-management/confluence-expert/`) — Documentation complements Jira workflows
- **Atlassian Admin** (`project-management/atlassian-admin/`) — Permission and user management for Jira projects

52
docs/skills/project-management/project-management.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: "Project Management Skills"
description: "Project Management Skills - Claude Code skill from the Project Management domain."
---
# Project Management Skills
**Domain:** Project Management | **Skill:** `project-management` | **Source:** [`project-management/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/SKILL.md)
---
# Project Management Skills
6 production-ready project management skills with Atlassian MCP integration.
## Quick Start
### Claude Code
```
/read project-management/jira-expert/SKILL.md
```
### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/project-management
```
## Skills Overview
| Skill | Folder | Focus |
|-------|--------|-------|
| Senior PM | `senior-pm/` | Portfolio management, risk analysis, resource planning |
| Scrum Master | `scrum-master/` | Velocity forecasting, sprint health, retrospectives |
| Jira Expert | `jira-expert/` | JQL queries, workflows, automation, dashboards |
| Confluence Expert | `confluence-expert/` | Knowledge bases, page layouts, macros |
| Atlassian Admin | `atlassian-admin/` | User management, permissions, integrations |
| Atlassian Templates | `atlassian-templates/` | Blueprints, custom layouts, reusable content |
## Python Tools
6 scripts, all stdlib-only:
```bash
python3 senior-pm/scripts/project_health_dashboard.py --help
python3 scrum-master/scripts/velocity_analyzer.py --help
```
## Rules
- Load only the specific skill SKILL.md you need
- Use MCP tools for live Jira/Confluence operations when available

7
docs/skills/project-management/scrum-master.md
View File

@@ -210,4 +210,11 @@ Apply stage-specific facilitation (details in `references/team-dynamics-framewor
--- ---
## Related Skills
- **Agile Product Owner** (`product-team/agile-product-owner/`) — User stories and backlog feed sprint planning
- **Senior PM** (`project-management/senior-pm/`) — Portfolio health context informs sprint priorities
---
*For deep framework references see `references/velocity-forecasting-guide.md` and `references/team-dynamics-framework.md`. For template assets see `assets/sprint_report_template.md` and `assets/team_health_check_template.md`.* *For deep framework references see `references/velocity-forecasting-guide.md` and `references/team-dynamics-framework.md`. For template assets see `assets/sprint_report_template.md` and `assets/team_health_check_template.md`.*

5
docs/skills/project-management/senior-pm.md
View File

@@ -408,3 +408,8 @@ Reference: `references/portfolio-kpis.md` for full definitions and measurement g
- Executive interview feedback on decision support quality - Executive interview feedback on decision support quality
- Team feedback on process efficiency and effectiveness - Team feedback on process efficiency and effectiveness
- Customer impact assessment of portfolio decisions - Customer impact assessment of portfolio decisions
## Related Skills
- **Product Strategist** (`product-team/product-strategist/`) — Product OKRs align with portfolio objectives
- **Scrum Master** (`project-management/scrum-master/`) — Sprint velocity data feeds project health dashboards

3
docs/skills/ra-qm-team/index.md
View File

@@ -5,7 +5,7 @@ description: "All Regulatory & Quality skills for Claude Code, OpenAI Codex, and
# Regulatory & Quality Skills # Regulatory & Quality Skills
12 skills in this domain. 13 skills in this domain.
| Skill | Description | | Skill | Description |
|-------|-------------| |-------|-------------|
@@ -19,5 +19,6 @@ description: "All Regulatory & Quality skills for Claude Code, OpenAI Codex, and
| [Quality Documentation Manager](quality-documentation-manager.md) | `quality-documentation-manager` | | [Quality Documentation Manager](quality-documentation-manager.md) | `quality-documentation-manager` |
| [Senior Quality Manager Responsible Person (QMR)](quality-manager-qmr.md) | `quality-manager-qmr` | | [Senior Quality Manager Responsible Person (QMR)](quality-manager-qmr.md) | `quality-manager-qmr` |
| [Quality Manager - QMS ISO 13485 Specialist](quality-manager-qms-iso13485.md) | `quality-manager-qms-iso13485` | | [Quality Manager - QMS ISO 13485 Specialist](quality-manager-qms-iso13485.md) | `quality-manager-qms-iso13485` |
| [Regulatory Affairs & Quality Management Skills](ra-qm-team.md) | `ra-qm-team` |
| [Head of Regulatory Affairs](regulatory-affairs-head.md) | `regulatory-affairs-head` | | [Head of Regulatory Affairs](regulatory-affairs-head.md) | `regulatory-affairs-head` |
| [Risk Management Specialist](risk-management-specialist.md) | `risk-management-specialist` | | [Risk Management Specialist](risk-management-specialist.md) | `risk-management-specialist` |

58
docs/skills/ra-qm-team/ra-qm-team.md Normal file
View File

@@ -0,0 +1,58 @@
---
title: "Regulatory Affairs & Quality Management Skills"
description: "Regulatory Affairs & Quality Management Skills - Claude Code skill from the Regulatory & Quality domain."
---
# Regulatory Affairs & Quality Management Skills
**Domain:** Regulatory & Quality | **Skill:** `ra-qm-team` | **Source:** [`ra-qm-team/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/SKILL.md)
---
# Regulatory Affairs & Quality Management Skills
12 production-ready compliance skills for HealthTech and MedTech organizations.
## Quick Start
### Claude Code
```
/read ra-qm-team/regulatory-affairs-head/SKILL.md
```
### Codex CLI
```bash
npx agent-skills-cli add alirezarezvani/claude-skills/ra-qm-team
```
## Skills Overview
| Skill | Folder | Focus |
|-------|--------|-------|
| Regulatory Affairs Head | `regulatory-affairs-head/` | FDA/MDR strategy, submissions |
| Quality Manager (QMR) | `quality-manager-qmr/` | QMS governance, management review |
| Quality Manager (ISO 13485) | `quality-manager-qms-iso13485/` | QMS implementation, doc control |
| Risk Management Specialist | `risk-management-specialist/` | ISO 14971, FMEA, risk files |
| CAPA Officer | `capa-officer/` | Root cause analysis, corrective actions |
| Quality Documentation Manager | `quality-documentation-manager/` | Document control, 21 CFR Part 11 |
| QMS Audit Expert | `qms-audit-expert/` | ISO 13485 internal audits |
| ISMS Audit Expert | `isms-audit-expert/` | ISO 27001 security audits |
| Information Security Manager | `information-security-manager-iso27001/` | ISMS implementation |
| MDR 745 Specialist | `mdr-745-specialist/` | EU MDR classification, CE marking |
| FDA Consultant | `fda-consultant-specialist/` | 510(k), PMA, QSR compliance |
| GDPR/DSGVO Expert | `gdpr-dsgvo-expert/` | Privacy compliance, DPIA |
## Python Tools
17 scripts, all stdlib-only:
```bash
python3 risk-management-specialist/scripts/risk_matrix_calculator.py --help
python3 gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py --help
```
## Rules
- Load only the specific skill SKILL.md you need
- Always verify compliance outputs against current regulations

2
mkdocs.yml
View File

@@ -1,6 +1,6 @@
site_name: Claude Code Skills & Plugins site_name: Claude Code Skills & Plugins
site_url: https://alirezarezvani.github.io/claude-skills site_url: https://alirezarezvani.github.io/claude-skills
site_description: "170 production-ready skills and plugins for Claude Code, OpenAI Codex, and OpenClaw. Reusable expertise for engineering, product, marketing, compliance, and more." site_description: "177 production-ready skills and plugins for Claude Code, OpenAI Codex, and OpenClaw. Reusable expertise for engineering, product, marketing, compliance, and more."
site_author: Alireza Rezvani site_author: Alireza Rezvani
repo_url: https://github.com/alirezarezvani/claude-skills repo_url: https://github.com/alirezarezvani/claude-skills
repo_name: alirezarezvani/claude-skills repo_name: alirezarezvani/claude-skills

52
product-team/CLAUDE.md
View File

@@ -1,6 +1,6 @@
# Product Team Skills - Claude Code Guidance # Product Team Skills - Claude Code Guidance
This guide covers the 5 production-ready product management skills and their Python automation tools. This guide covers the 8 production-ready product management skills and their Python automation tools.
## Product Skills Overview ## Product Skills Overview
@@ -10,8 +10,15 @@ This guide covers the 5 production-ready product management skills and their Pyt
3. **product-strategist/** - OKR cascade, strategic planning (1 tool) 3. **product-strategist/** - OKR cascade, strategic planning (1 tool)
4. **ux-researcher-designer/** - Persona generation, user research (1 tool) 4. **ux-researcher-designer/** - Persona generation, user research (1 tool)
5. **ui-design-system/** - Design token generation, component systems (1 tool) 5. **ui-design-system/** - Design token generation, component systems (1 tool)
6. **competitive-teardown/** - Competitive matrix building, gap analysis (1 tool)
7. **landing-page-generator/** - Landing page scaffolding (1 tool)
8. **saas-scaffolder/** - SaaS project bootstrapping (1 tool)
**Total Tools:** 6 Python automation tools **Total Tools:** 9 Python automation tools
**Agents:** 4 (cs-product-manager, cs-agile-product-owner, cs-product-strategist, cs-ux-researcher)
**Slash Commands:** 5 (/rice, /okr, /persona, /user-story, /competitive-matrix)
## Python Automation Tools ## Python Automation Tools
@@ -157,6 +164,33 @@ python ui-design-system/scripts/design_token_generator.py "#0066CC" modern scss
python ui-design-system/scripts/design_token_generator.py "#0066CC" modern json python ui-design-system/scripts/design_token_generator.py "#0066CC" modern json
``` ```
### 7. Competitive Matrix Builder (`competitive-teardown/scripts/competitive_matrix_builder.py`)
**Purpose:** Weighted competitive scoring with gap analysis
**Usage:**
```bash
python competitive-teardown/scripts/competitive_matrix_builder.py competitors.json
```
### 8. Landing Page Scaffolder (`landing-page-generator/scripts/landing_page_scaffolder.py`)
**Purpose:** Landing page template generation
**Usage:**
```bash
python landing-page-generator/scripts/landing_page_scaffolder.py config.json
```
### 9. Project Bootstrapper (`saas-scaffolder/scripts/project_bootstrapper.py`)
**Purpose:** SaaS project scaffolding with auth, billing, and API setup
**Usage:**
```bash
python saas-scaffolder/scripts/project_bootstrapper.py project_config.json
```
## Product Workflows ## Product Workflows
### Workflow 1: Feature Prioritization ### Workflow 1: Feature Prioritization
@@ -241,15 +275,12 @@ python ux-researcher-designer/scripts/persona_generator.py --output json > perso
## Roadmap ## Roadmap
**Current (Phase 1):** 5 skills deployed with 6 tools **Current (Phase 2):** 8 skills deployed with 9 tools, 4 agents, 5 commands
**Phase 2 (Q1 2026):** Product analytics **Next:** Product analytics
- A/B test analyzer - A/B test analyzer
- Funnel conversion tracker - Funnel conversion tracker
- Cohort retention analyzer - Cohort retention analyzer
**Phase 3 (Q2 2026):** Advanced PM tools
- Competitive analysis framework
- Product-market fit assessment - Product-market fit assessment
- Revenue impact calculator - Revenue impact calculator
@@ -263,6 +294,7 @@ See `product_team_implementation_guide.md` for detailed plans.
--- ---
**Last Updated:** November 5, 2025 **Last Updated:** March 9, 2026
**Skills Deployed:** 5/5 product skills production-ready **Skills Deployed:** 8/8 product skills production-ready
**Total Tools:** 6 Python automation tools **Total Tools:** 9 Python automation tools
**Agents:** 4 | **Commands:** 5

5
product-team/agile-product-owner/SKILL.md
View File

@@ -389,3 +389,8 @@ Story is complete when:
- [ ] Deployed to staging environment - [ ] Deployed to staging environment
- [ ] Product Owner accepted - [ ] Product Owner accepted
- [ ] No critical bugs remaining - [ ] No critical bugs remaining
## Related Skills
- **Scrum Master** (`project-management/scrum-master/`) — Velocity data and sprint ceremonies complement backlog management
- **Product Manager Toolkit** (`product-team/product-manager-toolkit/`) — RICE prioritization feeds backlog ordering

84
product-team/agile-product-owner/assets/sprint_planning_template.md Normal file
View File

@@ -0,0 +1,84 @@
# Sprint Planning Document
## Sprint Info
| Field | Value |
|-------|-------|
| **Sprint** | Sprint [Number] |
| **Dates** | [Start Date] - [End Date] |
| **Sprint Goal** | [One sentence describing what this sprint achieves] |
| **Scrum Master** | [Name] |
| **Product Owner** | [Name] |
---
## Sprint Goal
[Expand on the sprint goal. What is the single most important outcome? What does "done" look like for this sprint? 2-3 sentences.]
---
## Team Capacity
| Team Member | Available Days | Notes |
|------------|---------------|-------|
| [Name] | [X] / [Total] | [PTO, training, on-call, etc.] |
| [Name] | [X] / [Total] | |
| [Name] | [X] / [Total] | |
**Total Capacity:** [X] person-days
**Historical Velocity:** [X] story points (avg of last 3 sprints)
**Planned Velocity:** [X] story points (adjusted for capacity)
---
## Selected Stories
| # | Story | Points | Assignee | Priority | Status |
|---|-------|--------|----------|----------|--------|
| 1 | [Story title with ticket link] | [SP] | [Name] | Must Have | To Do |
| 2 | [Story title with ticket link] | [SP] | [Name] | Must Have | To Do |
| 3 | [Story title with ticket link] | [SP] | [Name] | Should Have | To Do |
| 4 | [Story title with ticket link] | [SP] | [Name] | Nice to Have | To Do |
**Total Planned:** [X] story points
---
## Dependencies
| Dependency | Blocking Story | Owner | Status | Due Date |
|-----------|---------------|-------|--------|----------|
| [External API ready] | [Story #] | [Name/Team] | [Status] | [Date] |
| [Design review complete] | [Story #] | [Name] | [Status] | [Date] |
---
## Risks
| Risk | Impact | Likelihood | Mitigation |
|------|--------|-----------|-----------|
| [Risk description] | High/Med/Low | High/Med/Low | [Plan] |
| [Risk description] | High/Med/Low | High/Med/Low | [Plan] |
---
## Definition of Done
- [ ] Code complete and peer reviewed
- [ ] Unit tests written and passing
- [ ] Acceptance criteria verified
- [ ] Documentation updated (if applicable)
- [ ] Deployed to staging environment
- [ ] QA sign-off received
- [ ] Product Owner acceptance
---
## Sprint Ceremonies
| Ceremony | Day/Time | Duration |
|----------|----------|----------|
| Daily Standup | [Day] [Time] | 15 min |
| Sprint Review | [Date] [Time] | 60 min |
| Sprint Retrospective | [Date] [Time] | 60 min |

60
product-team/agile-product-owner/assets/user_story_template.md Normal file
View File

@@ -0,0 +1,60 @@
# User Story
## Story Info
| Field | Value |
|-------|-------|
| **Title** | [Short descriptive title] |
| **Epic** | [Parent epic name/link] |
| **Story Points** | [Estimate] |
| **Priority** | Must Have / Should Have / Nice to Have |
| **Assignee** | [Name] |
| **Sprint** | [Sprint number] |
---
## User Story
**As a** [type of user/role],
**I want** [capability or feature],
**So that** [benefit or value I receive].
---
## Acceptance Criteria
### Scenario 1: [Happy Path]
- **Given** [precondition or context]
- **When** [action the user takes]
- **Then** [expected outcome]
### Scenario 2: [Alternative Path]
- **Given** [precondition or context]
- **When** [action the user takes]
- **Then** [expected outcome]
### Scenario 3: [Edge Case / Error]
- **Given** [precondition or context]
- **When** [action the user takes]
- **Then** [expected error handling or outcome]
---
## Notes
- [Technical notes, design references, API details]
- [Dependencies on other stories or external systems]
- [Out of scope items for this story]
- [Links to mockups, prototypes, or design files]
---
## Definition of Done
- [ ] Acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Product Owner accepted

5
product-team/competitive-teardown/SKILL.md
View File

@@ -164,3 +164,8 @@ Navigation: global search, keyboard shortcuts, in-app help.
5. **UX Highlights** — What they do better (3 bullets) vs. where we win (3 bullets) 5. **UX Highlights** — What they do better (3 bullets) vs. where we win (3 bullets)
6. **Voice of Customer** — Top 3 review complaints (quoted or paraphrased) 6. **Voice of Customer** — Top 3 review complaints (quoted or paraphrased)
7. **Our Action Plan** — Quick wins, medium-term, strategic priorities; Appendix with raw data 7. **Our Action Plan** — Quick wins, medium-term, strategic priorities; Appendix with raw data
## Related Skills
- **Product Strategist** (`product-team/product-strategist/`) — Competitive insights feed OKR and strategy planning
- **Landing Page Generator** (`product-team/landing-page-generator/`) — Competitive positioning informs landing page messaging

203
product-team/competitive-teardown/references/analysis-templates.md Normal file
View File

@@ -0,0 +1,203 @@
# Competitive Analysis Templates
## 1. SWOT Analysis Template
### Company/Product: [Competitor Name]
**Date:** [Analysis Date] | **Analyst:** [Name] | **Version:** [1.0]
#### Strengths (Internal Advantages)
| # | Strength | Evidence | Impact |
|---|----------|----------|--------|
| 1 | [e.g., Strong brand recognition] | [Source/data point] | High/Med/Low |
| 2 | | | |
| 3 | | | |
#### Weaknesses (Internal Limitations)
| # | Weakness | Evidence | Exploitability |
|---|----------|----------|---------------|
| 1 | [e.g., Limited API capabilities] | [Source/data point] | High/Med/Low |
| 2 | | | |
| 3 | | | |
#### Opportunities (External Favorable)
| # | Opportunity | Timeframe | Our Advantage |
|---|------------|-----------|---------------|
| 1 | [e.g., Competitor slow to adopt AI] | Short/Med/Long | [How we capitalize] |
| 2 | | | |
| 3 | | | |
#### Threats (External Unfavorable)
| # | Threat | Likelihood | Mitigation |
|---|--------|-----------|-----------|
| 1 | [e.g., Competitor acquired by larger company] | High/Med/Low | [Our response plan] |
| 2 | | | |
| 3 | | | |
---
## 2. Porter's Five Forces (Product Application)
### Market: [Your Product Category]
#### Force 1: Competitive Rivalry (Intensity: High/Med/Low)
- Number of direct competitors: ___
- Market growth rate: ___% annually
- Product differentiation level: High/Med/Low
- Switching costs for customers: High/Med/Low
- Exit barriers: High/Med/Low
- **Assessment:** [Summary of competitive rivalry intensity]
#### Force 2: Threat of New Entrants (Intensity: High/Med/Low)
- Capital requirements: High/Med/Low
- Technology barriers: High/Med/Low
- Network effects strength: Strong/Moderate/Weak
- Regulatory barriers: High/Med/Low
- Brand loyalty in market: Strong/Moderate/Weak
- **Assessment:** [Summary of new entrant threat]
#### Force 3: Threat of Substitutes (Intensity: High/Med/Low)
- Alternative solutions: [List substitutes]
- Price-performance of substitutes: Better/Same/Worse
- Switching costs to substitutes: High/Med/Low
- Customer propensity to switch: High/Med/Low
- **Assessment:** [Summary of substitute threat]
#### Force 4: Bargaining Power of Buyers (Power: High/Med/Low)
- Buyer concentration: Concentrated/Fragmented
- Price sensitivity: High/Med/Low
- Information availability: Full/Partial/Limited
- Switching costs: High/Med/Low
- Volume of purchases: High/Med/Low
- **Assessment:** [Summary of buyer power]
#### Force 5: Bargaining Power of Suppliers (Power: High/Med/Low)
- Key technology dependencies: [List]
- Cloud provider lock-in: High/Med/Low
- Talent market tightness: Tight/Balanced/Loose
- Data source dependencies: Critical/Important/Optional
- **Assessment:** [Summary of supplier power]
#### Overall Industry Attractiveness: [Score 1-10]
---
## 3. Competitive Positioning Map
### Axis Definitions
- **X-Axis:** [e.g., Ease of Use] (Low to High)
- **Y-Axis:** [e.g., Feature Completeness] (Low to High)
### Competitor Positions
| Competitor | X Score (1-10) | Y Score (1-10) | Quadrant |
|-----------|---------------|---------------|----------|
| Your Product | ___ | ___ | ___ |
| Competitor A | ___ | ___ | ___ |
| Competitor B | ___ | ___ | ___ |
| Competitor C | ___ | ___ | ___ |
| Competitor D | ___ | ___ | ___ |
### Quadrant Definitions
- **Top-Right (Leaders):** High on both axes - market leaders
- **Top-Left (Feature-Rich):** High features, lower ease of use - complex tools
- **Bottom-Right (Simple):** Easy to use, fewer features - niche players
- **Bottom-Left (Laggards):** Low on both axes - disruption candidates
### Positioning Insights
- **White space opportunities:** [Areas with no competitor presence]
- **Crowded areas:** [Where competition is fiercest]
- **Our trajectory:** [Direction we're moving on the map]
---
## 4. Win/Loss Analysis Template
### Deal: [Opportunity Name]
**Date:** [Close Date] | **Result:** Won / Lost | **Competitor:** [Name]
#### Deal Context
- **Deal Size:** $___
- **Sales Cycle:** ___ days
- **Segment:** SMB / Mid-Market / Enterprise
- **Industry:** ___
- **Decision Makers:** [Roles involved]
- **Evaluation Criteria:** [What mattered most to buyer]
#### Competitive Comparison (Buyer Perspective)
| Factor | Us (Score 1-5) | Competitor (Score 1-5) | Decisive? |
|--------|---------------|----------------------|-----------|
| Product Fit | | | Yes/No |
| Pricing | | | Yes/No |
| Ease of Use | | | Yes/No |
| Support Quality | | | Yes/No |
| Integration | | | Yes/No |
| Brand/Trust | | | Yes/No |
| Implementation | | | Yes/No |
#### Win/Loss Factors
- **Primary reason for outcome:** [Single most important factor]
- **Secondary factors:** [Supporting reasons]
- **Buyer quotes:** ["Direct quotes from debrief"]
#### Action Items
| # | Action | Owner | Due Date |
|---|--------|-------|----------|
| 1 | [e.g., Improve onboarding flow] | [Name] | [Date] |
| 2 | | | |
---
## 5. Battle Card Template
### Competitor: [Name]
**Last Updated:** [Date] | **Confidence:** High/Med/Low
#### Quick Facts
- **Founded:** ___
- **Funding:** $___
- **Employees:** ___
- **Customers:** ___
- **HQ:** ___
#### Elevator Pitch (Their Positioning)
> [How the competitor describes themselves in one sentence]
#### Our Positioning Against Them
> [How we differentiate - our one-liner against this competitor]
#### Where They Win
| Strength | Our Counter |
|----------|------------|
| [e.g., Lower price point] | [e.g., Emphasize TCO including implementation costs] |
| [e.g., Larger integration marketplace] | [e.g., Highlight quality over quantity, key integrations] |
| | |
#### Where We Win
| Our Strength | Evidence |
|-------------|----------|
| [e.g., Superior onboarding experience] | [Metric or customer quote] |
| [e.g., Better enterprise security] | [Certification or feature] |
| | |
#### Landmines to Set
Questions to ask prospects that expose competitor weaknesses:
1. "Have you evaluated how [specific capability] scales beyond [threshold]?"
2. "What's their approach to [area where competitor is weak]?"
3. "Can you share their uptime SLA and historical performance?"
#### Objection Handling
| Objection | Response |
|-----------|----------|
| "[Competitor] is cheaper" | [Value-based response] |
| "[Competitor] has more features" | [Quality/relevance response] |
| "We already use [Competitor]" | [Migration/coexistence story] |
#### Trap Questions They Set
Questions competitors ask about us, and how to respond:
1. **Q:** "[Our known weakness]?" **A:** [Honest, redirect response]
2. **Q:** "[Feature gap]?" **A:** [Roadmap or alternative approach]
#### Recent Intel
- [Date]: [Notable change - pricing, feature, hire, funding]
- [Date]: [Notable change]

104
product-team/competitive-teardown/references/data-collection-guide.md Normal file
View File

@@ -0,0 +1,104 @@
# Competitive Data Collection Guide
## Overview
This guide outlines systematic approaches for gathering competitive intelligence from publicly available sources. All methods described here are ethical and rely on information that competitors have made publicly accessible.
## Public Data Sources
### Review Platforms
- **G2**: Enterprise software reviews, feature comparisons, satisfaction scores
- **Capterra**: SMB-focused reviews, pricing transparency, deployment details
- **TrustRadius**: In-depth reviews with verified users, TrustMaps
- **Product Hunt**: Launch positioning, early adopter sentiment, feature highlights
- **App Store / Google Play**: Mobile app ratings, review themes, update frequency
### Company Publications
- **Pricing Pages**: Tier structure, feature gating, enterprise vs self-serve
- **Changelogs / Release Notes**: Development velocity, feature priorities, tech direction
- **Blog Posts**: Strategic messaging, thought leadership topics, market positioning
- **Case Studies**: Target customer profiles, value propositions, success metrics
- **Help Documentation**: Feature depth, API capabilities, integration ecosystem
### Talent & Organization Signals
- **Job Postings**: Technology stack, team growth areas, strategic initiatives
- **LinkedIn**: Team size, org structure, key hires, department ratios
- **Glassdoor**: Company culture, internal challenges, growth trajectory
### Financial & Legal
- **Patent Filings**: Innovation direction, defensive IP, technology differentiation
- **SEC Filings (public companies)**: Revenue, growth rate, customer count, churn
- **Crunchbase / PitchBook**: Funding rounds, investors, valuation trends
### Technical Intelligence
- **BuiltWith / Wappalyzer**: Technology stack detection
- **GitHub**: Open-source contributions, SDK quality, developer engagement
- **API Documentation**: Integration capabilities, rate limits, data models
- **Status Pages**: Uptime history, incident frequency, infrastructure maturity
## Data Points to Collect Per Competitor
### Product
- Core features and capabilities (feature-by-feature matrix)
- Unique differentiators and proprietary technology
- Platform support (web, mobile, desktop, API)
- Integration ecosystem (number and quality of integrations)
- Performance benchmarks (if available from reviews)
### Business
- Pricing tiers and per-seat/usage costs
- Target customer segments (SMB, mid-market, enterprise)
- Estimated customer count and notable logos
- Geographic focus and localization
- Go-to-market model (PLG, sales-led, hybrid)
### Team & Technology
- Estimated team size and engineering ratio
- Technology stack and infrastructure choices
- Development velocity (release frequency)
- Open-source involvement and developer relations
### Market Position
- Market share estimates
- Brand perception and NPS (from reviews)
- Analyst coverage (Gartner, Forrester positioning)
- Partnership and channel strategy
## Ethical Guidelines
1. **Use only public information** - Never access private systems, NDA-protected content, or internal documents
2. **No deception** - Do not misrepresent yourself to obtain information (e.g., fake sales inquiries)
3. **Respect terms of service** - Follow scraping policies and API usage terms
4. **Attribute sources** - Document where each data point came from for verification
5. **No employee poaching for intelligence** - Hiring decisions should be talent-driven, not intelligence-driven
6. **Legal compliance** - Ensure data collection complies with local regulations
## Update Cadence Recommendations
| Data Type | Frequency | Trigger Events |
|-----------|-----------|---------------|
| Pricing | Monthly | Competitor pricing page changes |
| Features | Bi-weekly | Changelog updates, product launches |
| Reviews | Monthly | Batch review analysis |
| Job Postings | Monthly | Hiring surge detection |
| Financials | Quarterly | Earnings reports, funding rounds |
| Tech Stack | Quarterly | Major platform changes |
| Full Teardown | Quarterly | Strategic planning cycles |
## Collection Workflow
1. **Set up monitoring** - Google Alerts, competitor RSS feeds, social listening
2. **Schedule regular sweeps** - Calendar recurring data collection tasks
3. **Centralize data** - Use a shared competitive intelligence database or spreadsheet
4. **Validate findings** - Cross-reference multiple sources for accuracy
5. **Tag and categorize** - Apply consistent taxonomy for easy retrieval
6. **Share insights** - Distribute relevant findings to product, sales, and marketing teams
7. **Archive versions** - Maintain historical snapshots for trend analysis
## Tools for Automation
- **Google Alerts**: Free monitoring for competitor mentions
- **Visualping**: Website change detection (pricing pages, feature pages)
- **Feedly**: RSS aggregation for competitor blogs and news
- **SimilarWeb**: Traffic estimates and audience overlap
- **SEMrush / Ahrefs**: SEO positioning and content strategy analysis

116
product-team/competitive-teardown/references/scoring-rubric.md Normal file
View File

@@ -0,0 +1,116 @@
# Competitive Scoring Rubric
## Overview
This rubric provides a standardized framework for evaluating competitors across key dimensions. Consistent scoring enables meaningful comparisons and tracks competitive position changes over time.
## Scoring Scale (1-10)
| Score | Label | Definition |
|-------|-------|-----------|
| 1-2 | Poor | Significant gaps, major usability issues, or missing capability |
| 3-4 | Below Average | Basic functionality with notable limitations |
| 5-6 | Average | Meets market expectations, no standout qualities |
| 7-8 | Above Average | Strong execution with clear advantages |
| 9-10 | Exceptional | Industry-leading, sets the standard for others |
## Dimension Categories
### 1. User Experience (UX) - Weight: 20%
- **Onboarding**: Time to first value, setup complexity, guided flows
- **Navigation**: Information architecture, discoverability, consistency
- **Visual Design**: Modern aesthetics, brand coherence, accessibility
- **Performance**: Page load times, responsiveness, offline capability
- **Mobile Experience**: Native app quality, responsive design, feature parity
### 2. Feature Completeness - Weight: 25%
- **Core Features**: Coverage of essential use cases
- **Advanced Features**: Power user capabilities, automation, customization
- **Workflow Support**: End-to-end process coverage without workarounds
- **API & Extensibility**: API coverage, webhook support, SDK quality
- **Innovation**: Unique capabilities not found in competitors
### 3. Pricing & Value - Weight: 15%
- **Transparency**: Clear pricing without hidden costs
- **Flexibility**: Plan options matching different customer sizes
- **Value-to-Cost Ratio**: Feature access relative to price point
- **Free Tier / Trial**: Quality of free offering for evaluation
- **Contract Terms**: Lock-in requirements, cancellation ease
### 4. Integrations - Weight: 10%
- **Native Integrations**: Number and quality of built-in connectors
- **Marketplace**: Third-party app ecosystem breadth
- **API Quality**: Documentation, reliability, rate limits
- **Data Import/Export**: Migration ease, format support
- **Workflow Automation**: Zapier, Make, native automation support
### 5. Support & Documentation - Weight: 10%
- **Documentation Quality**: Completeness, searchability, freshness
- **Support Channels**: Chat, email, phone, community availability
- **Response Time**: SLA adherence, resolution speed
- **Self-Service**: Knowledge base, video tutorials, community forums
- **Onboarding Support**: Dedicated CSM, implementation assistance
### 6. Performance & Reliability - Weight: 10%
- **Uptime**: Historical availability, SLA commitments
- **Speed**: Application responsiveness under normal load
- **Scalability**: Performance at high volume, enterprise readiness
- **Data Handling**: Large dataset support, bulk operations
- **Global Performance**: CDN, regional deployments, latency
### 7. Security & Compliance - Weight: 10%
- **Authentication**: SSO, MFA, RBAC granularity
- **Data Protection**: Encryption at rest and in transit, data residency
- **Certifications**: SOC 2, ISO 27001, GDPR, HIPAA compliance
- **Audit Trail**: Activity logging, access monitoring
- **Privacy Controls**: Data retention policies, right to deletion
## Weighting Guidelines
Default weights above suit most B2B SaaS evaluations. Adjust based on:
- **Enterprise buyers**: Increase Security (15%), Support (15%), reduce Pricing (10%)
- **Developer tools**: Increase Integrations (20%), Features (30%), reduce UX (10%)
- **SMB products**: Increase Pricing (25%), UX (25%), reduce Security (5%)
- **Regulated industries**: Increase Security (25%), reduce Features (15%)
## Calibration Process
1. **Anchor scoring** - Score your own product first to establish baseline
2. **Multiple scorers** - Have 2-3 team members score independently
3. **Discuss outliers** - Reconcile scores that differ by more than 2 points
4. **Document evidence** - Record specific examples justifying each score
5. **Normalize quarterly** - Re-calibrate as market expectations evolve
## Bias Mitigation
- **Avoid halo effect** - Score each dimension independently, not influenced by overall impression
- **Use evidence, not feelings** - Every score must link to observable data points
- **Include competitor strengths** - Resist tendency to under-score competitors
- **Rotate scorers** - Different team members bring fresh perspectives
- **Blind scoring** - When possible, evaluate features without knowing which competitor
- **Customer validation** - Compare internal scores against user review sentiment
## Composite Score Calculation
```
Weighted Score = SUM(Dimension Score x Dimension Weight)
Example:
UX(8) x 0.20 = 1.60
Features(7) x 0.25 = 1.75
Pricing(6) x 0.15 = 0.90
Integrations(8) x 0.10 = 0.80
Support(7) x 0.10 = 0.70
Performance(9) x 0.10 = 0.90
Security(8) x 0.10 = 0.80
---
Total = 7.45 / 10
```
## Output Format
Present results as a comparison matrix with color coding:
- Green (8-10): Competitive advantage
- Yellow (5-7): Market parity
- Red (1-4): Competitive gap

176
product-team/landing-page-generator/references/conversion-patterns.md Normal file
View File

@@ -0,0 +1,176 @@
# High-Converting Landing Page Patterns
## Overview
This reference catalogs proven landing page design patterns that drive higher conversion rates. Each pattern includes placement guidance, implementation notes, and A/B testing priorities.
## Hero Section Layouts
### Pattern 1: Left Copy + Right Product Screenshot
- **Best for:** SaaS products with a strong visual UI
- **Structure:** Headline, subheadline, CTA on left (60%); product screenshot on right (40%)
- **Why it works:** F-pattern reading leads with copy, product image provides proof
- **Conversion lift:** Baseline pattern, strong performer across industries
### Pattern 2: Centered Copy + Full-Width Background
- **Best for:** Brand-driven products, consumer apps
- **Structure:** Centered headline, subheadline, CTA over background image/gradient
- **Why it works:** Focuses attention on single message, high visual impact
- **Note:** Ensure text contrast against background for readability
### Pattern 3: Video Hero
- **Best for:** Complex products requiring demonstration
- **Structure:** Short headline + embedded video (60-90 seconds) + CTA below
- **Why it works:** Video explains what text cannot, increases time on page
- **Note:** Always include thumbnail; autoplay is often counterproductive
### Pattern 4: Interactive Demo
- **Best for:** Developer tools, data products, design tools
- **Structure:** Minimal copy + embedded interactive product experience
- **Why it works:** Hands-on experience converts better than description
- **Note:** Keep demo focused on one "aha moment" workflow
## Social Proof Placement
### Logo Bar
- **Position:** Immediately below hero section
- **Count:** 5-7 logos for credibility without clutter
- **Label:** "Trusted by" or "Used by teams at"
- **Selection:** Mix recognizable brands with relevant industry logos
### Testimonial Cards
- **Position:** After feature explanation sections
- **Format:** Photo + name + title + company + specific quote
- **Best quotes:** Include measurable outcomes ("Saved 10 hours/week")
- **Layout:** 2-3 testimonials in a row, carousel for more
### Case Study Callouts
- **Position:** Mid-page, before pricing
- **Format:** Company logo + headline metric + "Read the story" link
- **Example:** "Acme Corp reduced onboarding time by 60%"
### Social Proof Numbers
- **Position:** Near CTA or in dedicated trust section
- **Format:** Large number + descriptor (e.g., "50,000+ teams", "4.8/5 rating")
- **Selection:** Choose 3-4 most impressive metrics
## Pricing Table Designs
### Good/Better/Best (3-Tier)
- Most effective for SaaS with clear feature tiers
- Highlight recommended plan with visual emphasis
- Show annual discount prominently
- Include feature comparison matrix below
### Simple Two-Tier
- Free/Pro or Starter/Professional
- Best for PLG products with clear upgrade trigger
- Minimize decision fatigue
### Enterprise Custom
- Replace price with "Contact Sales" for high-ACV products
- List enterprise-specific features (SSO, SLA, dedicated support)
- Include a "Talk to Sales" CTA, not just a form
### Pricing Psychology
- Anchor with highest-priced plan first (or in the middle with visual highlight)
- Use monthly price with annual billing toggle
- Show savings percentage for annual plans
- Round prices ending in 9 (e.g., $49/mo, $99/mo)
## Trust Signals
### Security Badges
- SOC 2, ISO 27001, GDPR compliance badges
- SSL certificate indicator
- Place near forms and payment sections
### Guarantees
- Money-back guarantee with specific timeframe
- Free trial with no credit card requirement
- SLA uptime commitments
### Awards & Recognition
- Industry awards (best of, top rated)
- Analyst recognition (Gartner, Forrester, G2 Leader)
- Media mentions (as seen in logos)
### Real-Time Activity
- "X people signed up today" (use real data only)
- Recent activity feed
- Live user count
## Urgency Elements
### Ethical Urgency
- Limited-time pricing (with real deadline)
- Early adopter benefits (extra features, lower price)
- Cohort-based enrollment (actual capacity limits)
### Avoid
- Fake countdown timers that reset
- False scarcity ("only 3 left" when unlimited)
- Pressure tactics that erode trust
## Form Optimization
### Field Reduction
- Every additional field reduces conversion ~10%
- Start with email only, progressive profiling later
- Use single-column layouts for forms
### Smart Defaults
- Pre-fill country based on IP
- Auto-detect company from email domain
- Default to most popular plan
### Inline Validation
- Validate fields on blur, not on submit
- Show success states (green checkmark)
- Provide helpful error messages
### Multi-Step Forms
- Break long forms into 2-3 steps with progress indicator
- Put easiest questions first to build commitment
- Allow saving progress for complex forms
## Mobile-First Patterns
### Thumb-Friendly Design
- CTAs in thumb zone (bottom 40% of screen)
- Minimum tap target: 44x44px
- Adequate spacing between interactive elements
### Content Priority
- Lead with most compelling content (no scrolling to find CTA)
- Collapse secondary information into accordions
- Use sticky CTA bar on scroll
### Performance
- Target <3s load time on 3G
- Lazy-load images below fold
- Minimize JavaScript execution
## A/B Testing Priority Matrix
Test these elements in order of expected impact:
| Priority | Element | Expected Impact | Effort |
|----------|---------|----------------|--------|
| 1 | Headline | High | Low |
| 2 | CTA text and color | High | Low |
| 3 | Hero image/video | High | Medium |
| 4 | Social proof placement | Medium | Low |
| 5 | Form fields (fewer) | Medium | Low |
| 6 | Pricing presentation | Medium | Medium |
| 7 | Page length | Medium | High |
| 8 | Testimonial selection | Low | Low |
| 9 | Color scheme | Low | Medium |
| 10 | Font choices | Low | Low |
### Testing Best Practices
- Test one variable at a time for clear attribution
- Run tests for minimum 2 weeks or 1,000 visitors per variant
- Use 95% statistical significance threshold
- Document all test results for institutional knowledge
- Winner becomes new control for next test iteration

177
product-team/landing-page-generator/references/copy-frameworks.md Normal file
View File

@@ -0,0 +1,177 @@
# Landing Page Copywriting Frameworks
## Overview
Four copy frameworks with worked SaaS examples you can adapt. Each framework includes a complete before/after example plus specific guidelines for each section.
## 1. AIDA Framework (Attention - Interest - Desire - Action)
The classic direct response formula, ideal for product landing pages.
**Example — Project management SaaS:**
> **Attention:** "Your Team Loses 12 Hours Every Sprint to Status Meetings"
>
> **Interest:** "Engineering teams at Series A-C startups spend 23% of their week in sync meetings — not writing code. We tracked 847 teams over 6 months. The pattern was clear: the more people in a standup, the less code shipped that day."
>
> **Desire:** "Teams using AsyncStand ship 31% more story points per sprint. No more 15-person standups where 13 people zone out. Replace your daily sync with a 2-minute async check-in that your engineers actually complete (94% response rate vs 67% attendance for live standups)."
>
> **Action:** "Start Your Free 14-Day Trial — No Credit Card Required"
### Attention
- Lead with a specific, quantified pain point (not vague claims)
- Weak: "Save time on meetings" → Strong: "Your Team Loses 12 Hours Every Sprint to Status Meetings"
- Keep headlines under 10 words for maximum impact
### Interest
- Back up the headline with specific data or a relatable scenario
- Weak: "Meetings waste time" → Strong: "We tracked 847 teams — the more people in standup, the less code shipped that day"
- Use their language: mirror words from customer reviews, support tickets, and G2 feedback
### Desire
- Stack measurable outcomes, not features
- Weak: "AI-powered async updates" → Strong: "31% more story points per sprint, 94% response rate"
- Compare directly to the status quo they already endure
### Action
- Single, clear CTA with action-oriented verb
- Reduce friction: "No credit card required," "Set up in 2 minutes"
- Repeat CTA after each major content block
## 2. PAS Framework (Problem - Agitate - Solution)
Best for pain-point-driven products where the problem is well understood.
**Example — Expense management tool:**
> **Problem:** "Your finance team is still chasing receipts in Slack DMs."
>
> **Agitate:** "Last quarter, your team spent 46 hours manually reconciling expenses across email threads, shared drives, and 'I'll submit it later' promises. That's $4,200 in payroll — spent on data entry. And when audit season hits? Good luck finding that client dinner receipt from February."
>
> **Solution:** "Snap a photo of the receipt. ExpenseFlow auto-extracts vendor, amount, and category in 3 seconds. Your monthly close drops from 5 days to 1. 2,400 finance teams already made the switch."
### Problem
- Name the exact scenario (not the abstract category)
- Weak: "Expense tracking is hard" → Strong: "Your finance team is still chasing receipts in Slack DMs"
- Mirror language from reviews and support tickets
### Agitate
- Quantify the cost in dollars, hours, or missed opportunities
- Weak: "This costs you money" → Strong: "46 hours last quarter, $4,200 in payroll — on data entry"
- Acknowledge the workarounds they've tried and why those fail too
### Solution
- Lead with the user action, not the technology: "Snap a photo" not "AI-powered OCR"
- Include one proof point: number of customers, time saved, or before/after metric
- Make the mechanism clear in one sentence: what happens when they use it
## 3. BAB Framework (Before - After - Bridge)
Ideal for aspirational products and lifestyle-oriented landing pages.
**Example — Sales enablement platform:**
> **Before:** "It's 9 PM. You're rebuilding a deck for tomorrow's demo because the prospect is in healthcare, not fintech. You copy-paste from three old decks, pray the logos are right, and rehearse the new talk track in the shower."
>
> **After:** "It's 9 AM. You type 'healthcare, 200-bed hospital, HIPAA-concerned CTO.' DeckGen builds your slides in 40 seconds — case studies, compliance badges, ROI calculator pre-loaded. You walk into the call with the best deck your prospect has ever seen."
>
> **Bridge:** "DeckGen connects to your CRM, learns your win patterns, and generates prospect-specific decks in under a minute. 340 AEs at companies like Stripe and Notion already use it. Start free — your first 5 decks are on us."
### Before
- Describe a specific, lived moment — not an abstract pain category
- Weak: "Sales decks take too long" → Strong: "It's 9 PM. You're rebuilding a deck for tomorrow's demo..."
- Use second person and present tense to make it feel immediate
### After
- Same level of specificity — show the transformed version of that exact moment
- Include a measurable outcome: "40 seconds," "best deck your prospect has ever seen"
- The after state should feel effortless compared to the before
### Bridge
- Name the product explicitly and explain the mechanism in one sentence
- Include one social proof data point
- End with a low-friction CTA that connects to the after state
## 4. 4Ps Framework (Promise - Picture - Proof - Push)
Strong for SaaS and B2B landing pages with measurable outcomes.
### Promise
- Make a clear, specific, believable promise
- Tie it to a measurable outcome
- Example: "Reduce customer churn by 25% in 90 days"
### Picture
- Help the reader visualize success
- Use scenarios they can relate to
- Show the product in context (screenshots, demos)
### Proof
- Back the promise with evidence
- Customer testimonials with specific results
- Case studies with before/after metrics
- Third-party validation (awards, analyst reports)
### Push
- Give a compelling reason to act now
- Limited-time offer, bonus, or guarantee
- Risk reversal (money-back guarantee, free trial)
## Headline Formulas
### Benefit-Driven
- "Get [Desired Outcome] Without [Common Objection]"
- "[Specific Result] in [Timeframe]"
- "The [Adjective] Way to [Achieve Goal]"
### Problem-Driven
- "Stop [Painful Activity]. Start [Better Alternative]."
- "Tired of [Problem]? There's a Better Way."
- "[Problem]? Not Anymore."
### Social Proof-Driven
- "[Number] Teams Trust [Product] to [Outcome]"
- "Why [Notable Company] Switched to [Product]"
- "Rated #1 for [Category] by [Authority]"
### Question-Driven
- "What If You Could [Desirable Outcome]?"
- "Ready to [Transformation]?"
- "Still [Painful Status Quo]?"
## CTA Best Practices
### Language
- Use first-person: "Start My Free Trial" > "Start Your Free Trial"
- Be specific: "Get My Report" > "Submit"
- Include benefit: "Start Saving Time" > "Sign Up"
- Add urgency naturally: "Start Free Today" > "Sign Up Now!!!"
### Placement
- Primary CTA above the fold
- Repeat after each major content section
- Sticky CTA on scroll (mobile especially)
- Exit-intent as last chance
### Design
- High contrast color (stands out from page palette)
- Sufficient whitespace around the button
- Large enough to tap on mobile (min 44x44px)
- Micro-copy below button to reduce anxiety ("No credit card required")
## Above-the-Fold Principles
The first viewport must accomplish these goals within 5 seconds:
1. **Communicate what you do** - Clear, jargon-free headline
2. **Show who it's for** - Audience identification
3. **Demonstrate value** - Primary benefit or outcome
4. **Provide next step** - Visible CTA button
5. **Build credibility** - One trust signal (logo bar, metric, badge)
### Above-the-Fold Checklist
- [ ] Headline states primary benefit (under 10 words)
- [ ] Subheadline adds specificity or addresses objection
- [ ] Hero image/video shows product in use
- [ ] CTA button is visible without scrolling
- [ ] At least one trust signal present
- [ ] No jargon or ambiguity in messaging

109
product-team/landing-page-generator/references/seo-checklist.md Normal file
View File

@@ -0,0 +1,109 @@
# Landing Page SEO Checklist
## Overview
This checklist ensures landing pages are optimized for search engine visibility while maintaining conversion focus. Apply these checks before launching any landing page.
## Meta Tags
- [ ] **Title tag**: Under 60 characters, includes primary keyword, ends with brand name
- [ ] **Meta description**: 150-160 characters, includes CTA language, unique per page
- [ ] **Canonical URL**: Set to prevent duplicate content issues
- [ ] **Robots meta**: Ensure page is indexable (`index, follow`) unless intentionally noindex
- [ ] **Open Graph tags**: og:title, og:description, og:image, og:url for social sharing
- [ ] **Twitter Card tags**: twitter:card, twitter:title, twitter:description, twitter:image
- [ ] **Viewport meta**: `<meta name="viewport" content="width=device-width, initial-scale=1">`
## Structured Data
- [ ] **Organization schema**: Company name, logo, social profiles
- [ ] **Product schema**: Name, description, price, availability (for product pages)
- [ ] **FAQ schema**: For pages with FAQ sections (rich snippet opportunity)
- [ ] **Breadcrumb schema**: Navigation path for deep pages
- [ ] **Review schema**: Aggregate rating if testimonials present (use carefully per guidelines)
- [ ] **Validate**: Test all structured data with Google Rich Results Test
## Core Web Vitals Targets
### Largest Contentful Paint (LCP) - Target: < 2.5s
- [ ] Optimize hero image (WebP format, proper dimensions)
- [ ] Preload critical resources (`<link rel="preload">`)
- [ ] Use CDN for static assets
- [ ] Minimize render-blocking CSS and JavaScript
### First Input Delay (FID) / Interaction to Next Paint (INP) - Target: < 200ms
- [ ] Defer non-critical JavaScript
- [ ] Break up long tasks (>50ms)
- [ ] Minimize third-party script impact
- [ ] Use `requestAnimationFrame` for visual updates
### Cumulative Layout Shift (CLS) - Target: < 0.1
- [ ] Set explicit width/height on images and videos
- [ ] Reserve space for dynamic content (ads, embeds)
- [ ] Use `font-display: swap` for web fonts
- [ ] Avoid inserting content above existing content
## Keyword Placement
- [ ] **H1 tag**: Contains primary keyword, one per page only
- [ ] **H2 tags**: Include secondary keywords naturally
- [ ] **First paragraph**: Primary keyword appears in first 100 words
- [ ] **Body copy**: Natural keyword density (1-2%), no stuffing
- [ ] **Image alt text**: Descriptive, includes keyword where relevant
- [ ] **URL slug**: Short, keyword-rich, hyphen-separated
- [ ] **CTA text**: Consider keyword inclusion where natural
## Internal Linking
- [ ] Link to relevant product/feature pages
- [ ] Link to blog content that supports the page topic
- [ ] Use descriptive anchor text (not "click here")
- [ ] Ensure landing page is linked from main navigation or sitemap
- [ ] Link to pricing page if applicable
- [ ] Limit links to avoid diluting page authority (15-20 max)
## Image Optimization
- [ ] **Format**: Use WebP with JPEG/PNG fallback
- [ ] **Compression**: Lossy compression for photos, lossless for graphics
- [ ] **Dimensions**: Serve at exact display size (no CSS resizing)
- [ ] **Alt text**: Descriptive, 125 characters max, natural keyword inclusion
- [ ] **File names**: Descriptive, hyphenated (e.g., `product-dashboard-screenshot.webp`)
- [ ] **Lazy loading**: Apply to images below the fold (`loading="lazy"`)
- [ ] **Responsive images**: Use `srcset` for different viewport sizes
## Canonical URLs
- [ ] Self-referencing canonical on every page
- [ ] Consistent protocol (https) and trailing slash usage
- [ ] Canonical points to preferred URL version (www vs non-www)
- [ ] UTM parameters excluded from canonical URL
- [ ] Pagination handled with rel="next"/"prev" or single-page canonical
## Mobile Responsiveness
- [ ] **Mobile-friendly test**: Pass Google Mobile-Friendly Test
- [ ] **Touch targets**: Minimum 44x44px, 8px spacing between targets
- [ ] **Font size**: Minimum 16px base font, no pinch-to-zoom needed
- [ ] **Content parity**: All critical content accessible on mobile
- [ ] **Horizontal scroll**: None present at any viewport width
- [ ] **Form usability**: Appropriate input types (email, tel), autocomplete attributes
- [ ] **Media queries**: Breakpoints at 480px, 768px, 1024px, 1200px minimum
## Technical SEO
- [ ] **HTTPS**: SSL certificate valid and active
- [ ] **Page speed**: < 3s load time on mobile (test with PageSpeed Insights)
- [ ] **XML sitemap**: Page included in sitemap.xml
- [ ] **Robots.txt**: Page not blocked by robots.txt
- [ ] **404 handling**: Custom 404 page with navigation
- [ ] **Redirect chains**: No more than 1 redirect hop
- [ ] **Hreflang**: Set for multi-language landing pages
## Content Quality Signals
- [ ] **Unique content**: No duplicate content from other pages
- [ ] **Content depth**: Sufficient content for topic coverage (500+ words for SEO pages)
- [ ] **Readability**: Grade level 6-8 for broad audiences
- [ ] **Freshness**: Last modified date reflects recent updates
- [ ] **E-E-A-T signals**: Author expertise, company authority, trust indicators

132
product-team/product-manager-toolkit/assets/prd_template.md Normal file
View File

@@ -0,0 +1,132 @@
# Product Requirements Document (PRD)
## Document Info
| Field | Value |
|-------|-------|
| **Author** | [Your Name] |
| **Status** | Draft / In Review / Approved |
| **Created** | YYYY-MM-DD |
| **Last Updated** | YYYY-MM-DD |
| **Reviewers** | [Names] |
| **Target Release** | [Quarter or Date] |
---
## Problem Statement
### What problem are we solving?
[Describe the user problem in 2-3 sentences. Focus on the pain, not the solution.]
### Who is affected?
[Identify the user segment(s) experiencing this problem.]
### How do we know this is a problem?
[Link to evidence: interview insights, support tickets, analytics data, churn analysis.]
### What happens if we do nothing?
[Quantify the cost of inaction: lost revenue, churn risk, competitive disadvantage.]
---
## User Stories
| # | As a... | I want to... | So that... | Priority |
|---|---------|-------------|-----------|----------|
| 1 | [role] | [capability] | [benefit] | Must Have |
| 2 | [role] | [capability] | [benefit] | Should Have |
| 3 | [role] | [capability] | [benefit] | Nice to Have |
---
## Solution Overview
### Proposed Solution
[High-level description of what we will build. 3-5 sentences.]
### Key User Flows
[Describe the primary user interactions. Include wireframes or mockups if available.]
1. **Flow 1:** [Description]
2. **Flow 2:** [Description]
3. **Flow 3:** [Description]
### How It Works
[Explain the mechanism or approach. Include technical considerations if relevant.]
---
## Success Metrics
| Metric | Current | Target | Timeframe |
|--------|---------|--------|-----------|
| [Primary metric] | [Baseline] | [Goal] | [When] |
| [Secondary metric] | [Baseline] | [Goal] | [When] |
| [Guardrail metric] | [Baseline] | [Must not worsen] | [When] |
### How We Will Measure
[Describe tracking approach: analytics events, surveys, A/B test design.]
---
## Technical Requirements
### System Requirements
- [Requirement 1: e.g., API response time < 200ms]
- [Requirement 2: e.g., Support 10K concurrent users]
- [Requirement 3: e.g., Mobile responsive]
### Dependencies
- [Dependency 1: e.g., Payment service API update]
- [Dependency 2: e.g., Design system component]
### Security & Privacy
- [Data handling requirements]
- [Authentication/authorization needs]
- [Compliance considerations]
---
## Timeline
| Phase | Dates | Deliverables |
|-------|-------|-------------|
| Design | [Start - End] | Wireframes, user flows, design specs |
| Development | [Start - End] | Feature implementation, unit tests |
| QA | [Start - End] | Test plan execution, bug fixes |
| Beta | [Start - End] | Limited rollout, feedback collection |
| GA | [Date] | Full release, documentation, training |
---
## Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|-----------|
| [Risk 1] | High/Med/Low | High/Med/Low | [Plan] |
| [Risk 2] | High/Med/Low | High/Med/Low | [Plan] |
---
## Out of Scope
The following items are explicitly NOT included in this release:
- [Item 1: brief explanation of why]
- [Item 2: brief explanation of why]
- [Item 3: brief explanation of why]
---
## Decision Log
| # | Decision | Date | Decided By | Rationale |
|---|----------|------|-----------|-----------|
| 1 | [Decision] | [Date] | [Name] | [Why] |
---
## Change History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1 | [Date] | [Name] | Initial draft |

4
product-team/product-manager-toolkit/assets/rice_input_template.csv Normal file
View File

@@ -0,0 +1,4 @@
feature,reach,impact,confidence,effort
Example Feature 1,500,3,0.8,5
Example Feature 2,1000,2,0.9,3
Example Feature 3,300,1,1.0,2
1 feature reach impact confidence effort
2 Example Feature 1 500 3 0.8 5
3 Example Feature 2 1000 2 0.9 3
4 Example Feature 3 300 1 1.0 2

5
product-team/product-strategist/SKILL.md
View File

@@ -220,3 +220,8 @@ See `references/examples/sample_growth_okrs.json` for a complete example.
- Adjust contribution percentages based on team size - Adjust contribution percentages based on team size
- Platform/Infrastructure teams often support all objectives - Platform/Infrastructure teams often support all objectives
- Specialized teams (ML, Data) may only support relevant objectives - Specialized teams (ML, Data) may only support relevant objectives
## Related Skills
- **Senior PM** (`project-management/senior-pm/`) — Portfolio management and risk analysis inform strategic planning
- **Competitive Teardown** (`product-team/competitive-teardown/`) — Competitive intelligence feeds product strategy

106
product-team/product-strategist/assets/okr_template.md Normal file
View File

@@ -0,0 +1,106 @@
# OKR Planning Template
## Planning Info
| Field | Value |
|-------|-------|
| **Quarter** | [Q1/Q2/Q3/Q4 YYYY] |
| **Team** | [Team Name] |
| **Owner** | [Name] |
| **Status** | Planning / Active / Complete |
| **Tracking Cadence** | Weekly check-in, Monthly review |
---
## Company Objective
**[Company-level objective this product work supports]**
_Example: "Become the market leader in our category by delivering exceptional customer value"_
---
## Product Objective 1: [Objective Title]
_[Qualitative, inspirational statement. What does success look like?]_
### Key Results
| # | Key Result | Baseline | Target | Current | Status |
|---|-----------|----------|--------|---------|--------|
| 1.1 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
| 1.2 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
| 1.3 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
### Initiatives
| Initiative | Key Result | Owner | Status | Effort |
|-----------|-----------|-------|--------|--------|
| [Feature/project name] | KR 1.1 | [Name] | Not Started / In Progress / Complete | [T-shirt size] |
| [Feature/project name] | KR 1.2 | [Name] | Not Started / In Progress / Complete | [T-shirt size] |
---
## Product Objective 2: [Objective Title]
_[Qualitative, inspirational statement]_
### Key Results
| # | Key Result | Baseline | Target | Current | Status |
|---|-----------|----------|--------|---------|--------|
| 2.1 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
| 2.2 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
| 2.3 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
| 2.4 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
### Initiatives
| Initiative | Key Result | Owner | Status | Effort |
|-----------|-----------|-------|--------|--------|
| [Feature/project name] | KR 2.1 | [Name] | Not Started / In Progress / Complete | [T-shirt size] |
| [Feature/project name] | KR 2.2 | [Name] | Not Started / In Progress / Complete | [T-shirt size] |
---
## Product Objective 3: [Objective Title]
_[Qualitative, inspirational statement]_
### Key Results
| # | Key Result | Baseline | Target | Current | Status |
|---|-----------|----------|--------|---------|--------|
| 3.1 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
| 3.2 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
| 3.3 | [Measurable outcome] | [Current value] | [Target value] | [Progress] | On Track / At Risk / Off Track |
### Initiatives
| Initiative | Key Result | Owner | Status | Effort |
|-----------|-----------|-------|--------|--------|
| [Feature/project name] | KR 3.1 | [Name] | Not Started / In Progress / Complete | [T-shirt size] |
---
## Tracking
### Weekly Check-In Format
- **Confidence level** (1-10) for each key result
- **Blockers** identified and escalated
- **Adjustments** to initiatives if needed
### Monthly Review Format
- **Progress update** on all key results with data
- **Initiative status** review
- **Risk assessment** and mitigation updates
- **Stakeholder communication** summary
### End-of-Quarter Scoring
Score each key result 0.0 - 1.0:
- **1.0:** Fully achieved
- **0.7:** Strong progress, nearly there (ideal target)
- **0.4:** Meaningful progress but missed target
- **0.0:** No progress
_Note: Consistently scoring 1.0 means OKRs are not ambitious enough. Target 0.6-0.7 average._

182
product-team/saas-scaffolder/references/architecture-patterns.md Normal file
View File

@@ -0,0 +1,182 @@
# SaaS Architecture Patterns
## Overview
This reference covers the key architectural decisions when building SaaS applications. Each pattern includes trade-offs and decision criteria to help teams make informed choices early in the development process.
## Multi-Tenancy Models
### 1. Shared Database (Shared Schema)
All tenants share the same database and tables, distinguished by a `tenant_id` column.
**Pros:**
- Lowest infrastructure cost
- Simplest deployment and maintenance
- Easy cross-tenant analytics
- Fastest time to market
**Cons:**
- Risk of data leakage between tenants
- Noisy neighbor performance issues
- Complex data isolation enforcement
- Harder to meet data residency requirements
**Best for:** Early-stage products, SMB customers, cost-sensitive deployments
### 2. Schema-Per-Tenant
Each tenant gets their own database schema within a shared database instance.
**Pros:**
- Better data isolation than shared schema
- Easier per-tenant backup and restore
- Moderate infrastructure efficiency
- Can customize schema per tenant if needed
**Cons:**
- Schema migration complexity at scale (N migrations per update)
- Connection pooling challenges
- Database instance limits on schema count
- Moderate operational complexity
**Best for:** Mid-market products, moderate tenant count (100-1,000)
### 3. Database-Per-Tenant
Each tenant gets a completely separate database instance.
**Pros:**
- Maximum data isolation and security
- Per-tenant performance tuning
- Easy data residency compliance
- Simple per-tenant backup/restore
- No noisy neighbor issues
**Cons:**
- Highest infrastructure cost
- Complex deployment automation required
- Cross-tenant queries/analytics challenging
- Connection management overhead
**Best for:** Enterprise products, regulated industries (healthcare, finance), high-value customers
### Decision Matrix
| Factor | Shared DB | Schema-Per-Tenant | DB-Per-Tenant |
|--------|-----------|-------------------|---------------|
| Cost | Low | Medium | High |
| Isolation | Low | Medium | High |
| Scale (tenants) | 10,000+ | 100-1,000 | 10-100 |
| Compliance | Basic | Moderate | Full |
| Complexity | Low | Medium | High |
| Performance | Shared | Moderate | Dedicated |
## API-First Design
### Principles
1. **API before UI** - Design the API contract before building any frontend
2. **Versioning from day one** - Use URL versioning (`/v1/`) or header-based
3. **Consistent conventions** - RESTful resources, standard HTTP methods, consistent error format
4. **Documentation as code** - OpenAPI/Swagger specification maintained alongside code
### REST API Standards
- Use nouns for resources (`/users`, `/projects`)
- Use HTTP methods semantically (GET=read, POST=create, PUT=update, DELETE=remove)
- Return appropriate status codes (200, 201, 400, 401, 403, 404, 429, 500)
- Implement pagination (cursor-based for large datasets, offset for small)
- Support filtering, sorting, and field selection
- Rate limiting with clear headers (X-RateLimit-Limit, X-RateLimit-Remaining)
### API Design Checklist
- [ ] OpenAPI 3.0+ specification created
- [ ] Authentication (API keys, OAuth2, JWT) documented
- [ ] Error response format standardized
- [ ] Rate limiting implemented and documented
- [ ] Pagination strategy defined
- [ ] Webhook support for async events
- [ ] SDKs planned for primary languages
## Event-Driven Architecture
### When to Use
- Decoupling services that evolve independently
- Handling asynchronous workflows (notifications, integrations)
- Building audit trails and activity feeds
- Enabling real-time features (live updates, collaboration)
### Event Patterns
- **Event Notification**: Lightweight event triggers consumer to fetch data
- **Event-Carried State Transfer**: Event contains all needed data
- **Event Sourcing**: Store state as sequence of events, derive current state
### Implementation Options
- **Message Queues**: RabbitMQ, Amazon SQS (point-to-point)
- **Event Streams**: Apache Kafka, Amazon Kinesis (pub/sub, replay)
- **Managed PubSub**: Google Pub/Sub, AWS EventBridge
- **In-App**: Redis Streams for lightweight event handling
## CQRS (Command Query Responsibility Segregation)
### Pattern
- Separate read models (optimized for queries) from write models (optimized for commands)
- Write side handles business logic and validation
- Read side provides denormalized views for fast retrieval
### When to Use
- Read/write ratio is heavily skewed (90%+ reads)
- Complex domain logic on write side
- Different scaling needs for reads vs writes
- Multiple read representations of same data needed
### When to Avoid
- Simple CRUD applications
- Small-scale applications where complexity is not justified
- Teams without event-driven architecture experience
## Microservices vs Monolith Decision Matrix
| Factor | Monolith | Microservices |
|--------|----------|--------------|
| Team size | < 10 engineers | > 10 engineers |
| Product maturity | Early stage, exploring | Established, scaling |
| Deployment frequency | Weekly-monthly | Daily per service |
| Domain complexity | Single bounded context | Multiple bounded contexts |
| Scaling needs | Uniform | Service-specific |
| Operational maturity | Low (no DevOps team) | High (platform team) |
| Time to market | Faster initially | Slower initially, faster later |
### Recommended Path
1. **Start monolith** - Get to product-market fit fast
2. **Modular monolith** - Organize code into bounded contexts
3. **Extract services** - Move high-change or high-scale modules to services
4. **Full microservices** - Only when team and infrastructure justify it
## Serverless Considerations
### Good Fit
- Infrequent or bursty workloads
- Event-driven processing (webhooks, file processing, notifications)
- API endpoints with variable traffic
- Scheduled jobs and background tasks
### Poor Fit
- Long-running processes (>15 min)
- WebSocket connections
- Latency-sensitive operations (cold start impact)
- Heavy compute workloads
### Serverless Patterns for SaaS
- **API Gateway + Lambda**: HTTP request handling
- **Event processing**: S3/SQS triggers for async work
- **Scheduled tasks**: CloudWatch Events for cron jobs
- **Edge computing**: CloudFront Functions for personalization
## Infrastructure Recommendations by Stage
| Stage | Users | Architecture | Database | Hosting |
|-------|-------|-------------|----------|---------|
| MVP | 0-100 | Monolith | Shared PostgreSQL | Single server / PaaS |
| Growth | 100-10K | Modular monolith | Managed DB, read replicas | Auto-scaling group |
| Scale | 10K-100K | Service extraction | DB per service, caching | Kubernetes / ECS |
| Enterprise | 100K+ | Microservices | Polyglot persistence | Multi-region, CDN |

196
product-team/saas-scaffolder/references/auth-billing-guide.md Normal file
View File

@@ -0,0 +1,196 @@
# Authentication & Billing Implementation Guide
## Overview
Authentication and billing are foundational SaaS capabilities that affect every user interaction. This guide covers implementation patterns, security best practices, and common pitfalls for both systems.
## Authentication
### OAuth2 / OpenID Connect (OIDC) Flows
#### Authorization Code Flow (Recommended for Web Apps)
1. Redirect user to authorization server (`/authorize`)
2. User authenticates and consents
3. Authorization server redirects back with authorization code
4. Backend exchanges code for tokens (`/token`)
5. Store tokens server-side, issue session cookie
**Use when:** Server-rendered apps, traditional web applications
#### Authorization Code Flow + PKCE (Recommended for SPAs and Mobile)
1. Generate code verifier and code challenge
2. Redirect with code challenge
3. User authenticates
4. Exchange code + code verifier for tokens
5. Store tokens securely (memory for SPAs, secure storage for mobile)
**Use when:** Single-page applications, mobile apps, any public client
#### Client Credentials Flow
1. Service authenticates with client_id and client_secret
2. Receives access token for service-to-service calls
**Use when:** Backend service-to-service communication, no user context
### JWT Best Practices
**Token Structure:**
- **Access token**: Short-lived (15-60 minutes), contains user claims
- **Refresh token**: Longer-lived (7-30 days), stored securely, used to get new access tokens
- **ID token**: Contains user identity claims, used by frontend only
**Security Guidelines:**
- Sign tokens with RS256 (asymmetric) for distributed systems
- Include `iss`, `aud`, `exp`, `iat`, `sub` standard claims
- Never store sensitive data in JWT payload (it is base64-encoded, not encrypted)
- Validate all claims on every request
- Implement token rotation for refresh tokens
- Maintain a deny-list for revoked tokens (or use short-lived access tokens)
- Set `httpOnly`, `secure`, `sameSite=strict` for cookie-stored tokens
**Common Pitfalls:**
- Using HS256 in distributed systems (shared secret)
- Storing JWTs in localStorage (XSS vulnerable)
- Not validating `aud` claim (token reuse attacks)
- Excessively long access token lifetimes
### RBAC vs ABAC
#### Role-Based Access Control (RBAC)
- Assign users to roles (Admin, Editor, Viewer)
- Roles have fixed permission sets
- Simple to implement and understand
- Works well for most SaaS applications
**Implementation:**
```
User -> Role -> Permissions
john@acme.com -> Admin -> [create, read, update, delete, manage_users]
jane@acme.com -> Editor -> [create, read, update]
bob@acme.com -> Viewer -> [read]
```
#### Attribute-Based Access Control (ABAC)
- Decisions based on user attributes, resource attributes, environment
- More flexible but more complex
- Required for fine-grained access control
**Use ABAC when:**
- Access depends on resource ownership (users can edit their own posts)
- Multi-tenant isolation requires tenant-context checks
- Time-based or location-based access rules needed
- Regulatory compliance requires granular audit trails
### Social Login Implementation
- Support Google, GitHub, Microsoft at minimum for B2B
- Map social identity to internal user record (by email)
- Handle account linking (same email, different providers)
- Always allow email/password as fallback
- Implement account deduplication strategy
## Billing & Subscriptions
### Stripe Integration Patterns
#### Setup Flow
1. Create Stripe Customer on user registration
2. Store `stripe_customer_id` in your database
3. Use Stripe Checkout for initial payment (PCI-compliant)
4. Store `subscription_id` for ongoing management
5. Sync plan status via webhooks (source of truth)
#### Key Stripe Objects
- **Customer**: Maps to your user/organization
- **Product**: Maps to your plan tier (Basic, Pro, Enterprise)
- **Price**: Specific pricing for a product (monthly, annual)
- **Subscription**: Active billing relationship
- **Invoice**: Generated per billing cycle
- **PaymentIntent**: Represents a payment attempt
### Subscription Lifecycle
#### Trial Period
- Offer 7-14 day free trial (no credit card for PLG, card required for sales-led)
- Send reminder emails at 3 days and 1 day before trial ends
- Provide clear upgrade path within the product
- Track trial engagement to predict conversion
#### Active Subscription
- Sync plan features with entitlement system
- Handle plan upgrades (immediate proration) and downgrades (end of period)
- Support annual billing with discount (typically 15-20%)
- Send receipts and invoice notifications
#### Payment Failure / Dunning
1. First failure: Retry automatically, notify user
2. Second failure (3 days later): Retry, send warning email
3. Third failure (7 days later): Retry, restrict features
4. Final attempt (14 days): Cancel subscription, move to free tier
5. Win-back: Send recovery emails at 30, 60, 90 days
#### Churned
- Downgrade to free tier (maintain data for re-activation)
- Track churn reason (survey on cancellation)
- Implement cancellation flow with save offers
- Define data retention policy (90 days typical)
#### Reactivated
- Allow easy re-subscription from settings
- Restore previous plan and data
- Consider win-back offers (discount for first month back)
### Webhook Handling
**Critical Webhooks to Handle:**
- `customer.subscription.created` - Activate plan
- `customer.subscription.updated` - Sync plan changes
- `customer.subscription.deleted` - Handle cancellation
- `invoice.paid` - Confirm payment, update status
- `invoice.payment_failed` - Trigger dunning flow
- `checkout.session.completed` - Complete signup flow
**Webhook Best Practices:**
- Verify webhook signature on every request
- Respond with 200 immediately, process asynchronously
- Implement idempotency (handle duplicate events)
- Log all webhook events for debugging
- Set up webhook failure alerts
- Use Stripe CLI for local development testing
### PCI Compliance Basics
#### SAQ-A (Recommended for SaaS)
- Use Stripe.js / Stripe Elements for card collection
- Never touch raw card numbers on your servers
- Card data goes directly from browser to Stripe
- Your servers only handle tokens and customer IDs
#### Requirements
- [ ] Use HTTPS everywhere
- [ ] Never log card numbers or CVV
- [ ] Use Stripe-hosted payment forms or Elements
- [ ] Restrict access to Stripe dashboard (2FA required)
- [ ] Regularly rotate API keys
- [ ] Document your payment processing flow
## Entitlement System Design
### Feature Gating Pattern
```
Check flow:
1. User action requested
2. Look up user's subscription plan
3. Check plan's feature flags / limits
4. Allow or deny with appropriate message
```
### Entitlement Types
- **Boolean**: Feature on/off (e.g., "SSO enabled")
- **Numeric limit**: Usage cap (e.g., "10 projects max")
- **Tiered**: Different capability levels (e.g., "basic/advanced analytics")
### Implementation Tips
- Cache entitlements locally (refresh on plan change webhook)
- Show upgrade prompts at limit boundaries (not hard blocks)
- Provide grace periods for brief overages
- Track usage for plan recommendation engine

278
product-team/saas-scaffolder/references/tech-stack-comparison.md Normal file
View File

@@ -0,0 +1,278 @@
# Technology Stack Comparison
## Overview
Choosing the right technology stack is one of the most impactful early decisions for a SaaS product. This comparison covers the most popular options across frontend, backend, database, and caching layers, with decision criteria for each.
## Frontend Frameworks
### Next.js (React)
**Strengths:**
- Largest ecosystem and community
- Excellent developer tooling and documentation
- Server-side rendering (SSR) and static generation (SSG) built in
- Vercel deployment makes hosting trivial
- App Router with React Server Components for optimal performance
- Rich component library ecosystem (shadcn/ui, Radix, Chakra)
**Weaknesses:**
- React learning curve (hooks, state management, rendering model)
- Bundle size can grow without discipline
- Vercel lock-in concerns for advanced features
- Frequent major version changes
**Best for:** Most SaaS products, teams with React experience, SEO-important pages
### Remix (React)
**Strengths:**
- Web standards focused (forms, HTTP, progressive enhancement)
- Excellent data loading patterns (loaders/actions)
- Built-in error boundaries and optimistic UI
- Works without JavaScript enabled
- Strong TypeScript support
- Deployable anywhere (not tied to specific platform)
**Weaknesses:**
- Smaller ecosystem than Next.js
- Fewer deployment guides and hosting templates
- Less community content and tutorials
- Now merged into React Router v7 (transition period)
**Best for:** Data-heavy applications, teams valuing web standards, progressive enhancement needs
### SvelteKit (Svelte)
**Strengths:**
- Smallest bundle sizes (compiler-based, no virtual DOM)
- Simplest learning curve among frameworks
- Built-in state management (reactive declarations)
- Excellent performance out of the box
- Growing ecosystem and community
- First-class TypeScript support
**Weaknesses:**
- Smaller ecosystem and component library selection
- Fewer developers in hiring pool
- Less enterprise adoption (harder to find case studies)
- Fewer third-party integrations
**Best for:** Performance-critical applications, small teams wanting simplicity, developer experience priority
### Frontend Decision Criteria
| Criterion | Next.js | Remix | SvelteKit |
|-----------|---------|-------|-----------|
| Ecosystem Size | Large | Medium | Growing |
| Learning Curve | Medium | Medium | Low |
| Performance | Good | Good | Excellent |
| SSR/SSG | Excellent | Good | Good |
| Hiring Pool | Large | Small | Small |
| Bundle Size | Medium | Small | Smallest |
| TypeScript | Excellent | Excellent | Excellent |
| Deployment Flexibility | Medium | High | High |
## Backend Frameworks
### Node.js (Express / Fastify / NestJS)
**Strengths:**
- Same language as frontend (JavaScript/TypeScript full-stack)
- Massive npm ecosystem
- NestJS provides enterprise patterns (DI, modules, decorators)
- Excellent for I/O-heavy workloads
- Large community and hiring pool
- Great for real-time features (WebSockets)
**Weaknesses:**
- Single-threaded (CPU-intensive tasks require workers)
- Callback/async complexity
- npm dependency security concerns
- Less suited for computational workloads
**Best for:** Full-stack TypeScript teams, real-time applications, API-heavy products
### Python (FastAPI / Django)
**Strengths:**
- FastAPI: Modern, fast, automatic OpenAPI docs, async support
- Django: Batteries included (admin, ORM, auth, migrations)
- Excellent for data processing and ML integration
- Clean, readable syntax
- Strong ecosystem for analytics and data work
- Large hiring pool across web and data roles
**Weaknesses:**
- Slower runtime than Go/Rust (mitigated by async in FastAPI)
- GIL limits true parallelism (multiprocessing required)
- Django can feel heavyweight for microservices
- Deployment can be more complex (WSGI/ASGI setup)
**Best for:** Data-heavy products, ML integration, rapid prototyping, admin-heavy applications
### Go (Gin / Echo / Fiber)
**Strengths:**
- Excellent performance (compiled, concurrent by design)
- Low memory footprint
- Simple deployment (single binary, no runtime)
- Built-in concurrency (goroutines, channels)
- Strong standard library
- Fast compilation
**Weaknesses:**
- Smaller web ecosystem than Node.js or Python
- More verbose for CRUD operations
- Error handling verbosity
- Fewer ORM options (GORM is the main choice)
- Steeper learning curve for teams from dynamic languages
**Best for:** High-throughput APIs, microservices, infrastructure tooling, performance-critical backends
### Backend Decision Criteria
| Criterion | Node.js | Python | Go |
|-----------|---------|--------|-----|
| Performance | Good | Moderate | Excellent |
| Developer Productivity | High | High | Medium |
| Ecosystem | Largest | Large | Medium |
| Hiring Pool | Large | Large | Medium |
| Full-Stack Synergy | Excellent | None | None |
| Data/ML Integration | Medium | Excellent | Low |
| Concurrency | Event Loop | Async/Threads | Goroutines |
| Deployment Simplicity | Medium | Medium | High |
## Database
### PostgreSQL
**Strengths:**
- ACID compliant with excellent reliability
- Rich feature set (JSON, full-text search, GIS, arrays)
- Extensible (custom types, functions, extensions like PostGIS, pgvector)
- Strong community and tooling
- Excellent for complex queries and analytics
- Free and open source with managed options (AWS RDS, Supabase, Neon)
**Weaknesses:**
- Horizontal scaling requires effort (Citus, partitioning)
- More complex initial setup than MySQL
- VACUUM maintenance at high write volumes
- Slightly slower for simple read-heavy workloads vs MySQL
**Best for:** Most SaaS applications (recommended default), complex data models, JSON workloads
### MySQL
**Strengths:**
- Proven at massive scale (Meta, Uber, Shopify)
- Simpler replication setup
- Faster for simple read-heavy workloads
- PlanetScale offers serverless MySQL with branching
- Wide hosting support
**Weaknesses:**
- Fewer advanced features than PostgreSQL
- Weaker JSON support
- Less extensible
- InnoDB limitations for certain workloads
**Best for:** Read-heavy applications, teams with MySQL expertise, PlanetScale users
### Database Decision Criteria
| Criterion | PostgreSQL | MySQL |
|-----------|-----------|-------|
| Feature Richness | Excellent | Good |
| JSON Support | Excellent | Moderate |
| Replication | Good | Good |
| Horizontal Scale | Moderate | Good (PlanetScale) |
| Community | Excellent | Excellent |
| Managed Options | Many | Many |
| Learning Curve | Medium | Low |
| Default Choice | Yes | Situational |
## Caching Layer
### Redis
**Strengths:**
- Rich data structures (strings, hashes, lists, sets, sorted sets, streams)
- Pub/Sub for real-time messaging
- Lua scripting for atomic operations
- Persistence options (RDB, AOF)
- Cluster mode for horizontal scaling
- Used for caching, sessions, queues, rate limiting, leaderboards
**Weaknesses:**
- Memory-bound (dataset must fit in RAM)
- Single-threaded command processing
- Licensing changes (Redis 7.4+ source-available)
- Cluster mode adds complexity
**Best for:** Most SaaS applications (recommended default), session management, rate limiting, queues
### Memcached
**Strengths:**
- Simplest possible key-value cache
- Multi-threaded (better CPU utilization for simple operations)
- Lower memory overhead per key
- Predictable performance characteristics
- Battle-tested at scale
**Weaknesses:**
- No data structures (strings only)
- No persistence
- No pub/sub or scripting
- No built-in clustering (client-side sharding)
- Limited eviction policies
**Best for:** Pure caching use cases, simple key-value lookups, memory efficiency priority
### Cache Decision Criteria
| Criterion | Redis | Memcached |
|-----------|-------|-----------|
| Data Structures | Rich | Strings Only |
| Persistence | Yes | No |
| Pub/Sub | Yes | No |
| Multi-Threading | No (I/O threads in v6) | Yes |
| Use Cases | Many | Caching Only |
| Memory Efficiency | Good | Better |
| Default Choice | Yes | Rarely |
## Recommended Stacks by Product Type
### B2B SaaS (Most Common)
- **Frontend:** Next.js + TypeScript + shadcn/ui
- **Backend:** Node.js (NestJS) or Python (FastAPI)
- **Database:** PostgreSQL
- **Cache:** Redis
- **Auth:** Auth0 or Clerk
- **Payments:** Stripe
### Developer Tool / API Product
- **Frontend:** Next.js or SvelteKit
- **Backend:** Go (Gin) or Node.js (Fastify)
- **Database:** PostgreSQL
- **Cache:** Redis
- **Auth:** Custom JWT + API Keys
- **Docs:** Mintlify or ReadMe
### Data-Heavy / Analytics Product
- **Frontend:** Next.js
- **Backend:** Python (FastAPI)
- **Database:** PostgreSQL + ClickHouse (analytics)
- **Cache:** Redis
- **Processing:** Celery or Temporal
- **Visualization:** Custom or embedded (Metabase)
### Real-Time / Collaboration Product
- **Frontend:** Next.js or SvelteKit
- **Backend:** Node.js (Fastify) + WebSockets
- **Database:** PostgreSQL + Redis (pub/sub)
- **Cache:** Redis
- **Real-Time:** Socket.io or Liveblocks
- **CRDT:** Yjs or Automerge (for collaborative editing)

180
product-team/ui-design-system/assets/design_system_doc_template.md Normal file
View File

@@ -0,0 +1,180 @@
# Design System Documentation
## System Info
| Field | Value |
|-------|-------|
| **Name** | [Design System Name] |
| **Version** | [X.Y.Z] |
| **Owner** | [Team/Person] |
| **Status** | Active / Beta / Deprecated |
| **Last Updated** | YYYY-MM-DD |
---
## Design Principles
The following principles guide all design decisions in this system:
1. **[Principle 1 Name]** - [One sentence description. Example: "Clarity over cleverness - every element should have an obvious purpose."]
2. **[Principle 2 Name]** - [One sentence description. Example: "Consistency breeds confidence - similar actions should look and behave the same."]
3. **[Principle 3 Name]** - [One sentence description. Example: "Accessible by default - every component must meet WCAG 2.1 AA standards."]
4. **[Principle 4 Name]** - [One sentence description. Example: "Progressive disclosure - show only what is needed, reveal complexity on demand."]
---
## Color Palette
### Brand Colors
| Name | Hex | RGB | Usage |
|------|-----|-----|-------|
| Primary | #[XXXXXX] | rgb(X, X, X) | Primary actions, links, key UI elements |
| Secondary | #[XXXXXX] | rgb(X, X, X) | Secondary actions, accents |
| Accent | #[XXXXXX] | rgb(X, X, X) | Highlights, badges, notifications |
### Neutral Colors
| Name | Hex | Usage |
|------|-----|-------|
| Gray-900 | #[XXXXXX] | Primary text |
| Gray-700 | #[XXXXXX] | Secondary text |
| Gray-500 | #[XXXXXX] | Placeholder text, disabled states |
| Gray-300 | #[XXXXXX] | Borders, dividers |
| Gray-100 | #[XXXXXX] | Backgrounds, hover states |
| White | #FFFFFF | Page background, card background |
### Semantic Colors
| Name | Hex | Usage |
|------|-----|-------|
| Success | #[XXXXXX] | Success messages, positive indicators |
| Warning | #[XXXXXX] | Warning messages, caution indicators |
| Error | #[XXXXXX] | Error messages, destructive actions |
| Info | #[XXXXXX] | Informational messages, tips |
### Accessibility
- All text colors must meet WCAG 2.1 AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
- Test with color blindness simulators
- Never use color as the only indicator of state
---
## Typography Scale
### Font Family
- **Primary:** [Font Name] (headings and body)
- **Monospace:** [Font Name] (code blocks, technical content)
- **Fallback Stack:** [System font stack]
### Type Scale
| Name | Size | Weight | Line Height | Usage |
|------|------|--------|-------------|-------|
| Display | 48px / 3rem | Bold (700) | 1.2 | Hero headings |
| H1 | 36px / 2.25rem | Bold (700) | 1.25 | Page titles |
| H2 | 28px / 1.75rem | Semibold (600) | 1.3 | Section headings |
| H3 | 22px / 1.375rem | Semibold (600) | 1.35 | Subsection headings |
| H4 | 18px / 1.125rem | Medium (500) | 1.4 | Card titles, labels |
| Body Large | 18px / 1.125rem | Regular (400) | 1.6 | Lead paragraphs |
| Body | 16px / 1rem | Regular (400) | 1.5 | Default body text |
| Body Small | 14px / 0.875rem | Regular (400) | 1.5 | Secondary text, captions |
| Caption | 12px / 0.75rem | Regular (400) | 1.4 | Labels, metadata |
---
## Spacing System
### Base Unit: 4px
| Token | Value | Usage |
|-------|-------|-------|
| space-1 | 4px | Tight spacing (icon padding) |
| space-2 | 8px | Compact elements (inline items) |
| space-3 | 12px | Related elements (form field gaps) |
| space-4 | 16px | Default spacing (paragraph gaps) |
| space-5 | 20px | Group spacing (card padding) |
| space-6 | 24px | Section spacing |
| space-8 | 32px | Large section gaps |
| space-10 | 40px | Page section dividers |
| space-12 | 48px | Major layout sections |
| space-16 | 64px | Page-level spacing |
### Layout Spacing
- **Page margin:** space-6 (mobile), space-8 (tablet), space-12 (desktop)
- **Card padding:** space-5
- **Form field gap:** space-3
- **Section gap:** space-10
---
## Component Library
### Component Status Legend
- **Stable** - Production ready, fully documented and tested
- **Beta** - Functional but may change, use with awareness
- **Deprecated** - Scheduled for removal, migrate to replacement
- **Planned** - On roadmap, not yet available
### Components
| Component | Status | Description | Variants |
|-----------|--------|-------------|----------|
| Button | Stable | Primary action triggers | Primary, Secondary, Tertiary, Danger, Ghost |
| Input | Stable | Text input fields | Default, Error, Disabled, With icon |
| Select | Stable | Dropdown selection | Single, Multi, Searchable |
| Checkbox | Stable | Multi-select toggle | Default, Indeterminate, Disabled |
| Radio | Stable | Single-select option | Default, Disabled |
| Toggle | Stable | Binary on/off switch | Default, With label |
| Modal | Stable | Overlay dialog | Small, Medium, Large, Fullscreen |
| Toast | Stable | Temporary notification | Success, Error, Warning, Info |
| Card | Stable | Content container | Default, Interactive, Elevated |
| Badge | Stable | Status indicator | Solid, Outline, Dot |
| Avatar | Stable | User representation | Image, Initials, Icon |
| Table | Beta | Data display grid | Default, Sortable, Selectable |
| Tabs | Beta | Content organization | Default, Underline, Pill |
| Tooltip | Stable | Contextual information | Default, Rich content |
| [New Component] | Planned | [Description] | [Variants] |
---
## Usage Guidelines
### Do
- Use components as documented (do not override internal styles)
- Follow the spacing system for consistent layouts
- Test components across supported browsers and screen sizes
- Use semantic colors for their intended purpose
- Reference design tokens instead of hardcoded values
### Do Not
- Modify component internals without contributing changes back
- Create one-off components when an existing component fits
- Use brand colors for semantic purposes (error, success)
- Skip accessibility requirements for "internal" tools
- Mix design system versions across a single application
---
## Contribution Process
### Proposing a New Component
1. **Check existing components** - Verify no existing component solves the need
2. **Create proposal** - Document use case, behavior, variants, accessibility requirements
3. **Design review** - Present to design system team for feedback
4. **Build** - Implement component following system patterns
5. **Review** - Code review + design review + accessibility audit
6. **Document** - Add to component library with usage guidelines
7. **Release** - Publish in next minor version
### Updating an Existing Component
1. **File issue** - Describe the change and justification
2. **Impact assessment** - Identify all instances of current usage
3. **Design + develop** - Implement change with backward compatibility
4. **Migration guide** - Document breaking changes if any
5. **Release** - Publish with changelog entry
### Reporting Issues
- File bug reports with reproduction steps and screenshots
- Tag with component name and severity
- Include browser/OS information for rendering issues

5
product-team/ux-researcher-designer/SKILL.md
View File

@@ -412,3 +412,8 @@ Detailed reference guides in `references/`:
- [ ] Findings include evidence - [ ] Findings include evidence
- [ ] Recommendations are actionable - [ ] Recommendations are actionable
- [ ] Priorities justified - [ ] Priorities justified
## Related Skills
- **UI Design System** (`product-team/ui-design-system/`) — Research findings inform design system decisions
- **Product Manager Toolkit** (`product-team/product-manager-toolkit/`) — Customer interview analysis complements persona research

162
product-team/ux-researcher-designer/assets/research_plan_template.md Normal file
View File

@@ -0,0 +1,162 @@
# UX Research Plan
## Study Info
| Field | Value |
|-------|-------|
| **Study Name** | [Descriptive name] |
| **Researcher** | [Name] |
| **Stakeholders** | [Names/roles] |
| **Status** | Planning / In Field / Analysis / Complete |
| **Timeline** | [Start Date] - [End Date] |
---
## Research Questions
What do we need to learn? List 3-5 specific, answerable questions.
1. [Primary question - the most important thing to learn]
2. [Secondary question]
3. [Secondary question]
4. [Exploratory question - nice to know]
5. [Exploratory question - nice to know]
### What We Already Know
[Summarize existing knowledge, past research, analytics data, assumptions to validate.]
### What We Do Not Know
[List specific knowledge gaps this study will address.]
---
## Methodology
**Method:** [Usability Testing / User Interviews / Survey / Diary Study / Card Sorting / A/B Test / Contextual Inquiry]
**Justification:** [Why this method is appropriate for the research questions.]
**Approach:** [Moderated / Unmoderated / Remote / In-Person]
**Duration:** [Session length per participant]
**Tools:** [Platform/tools used - e.g., Lookback, Maze, UserTesting, Zoom]
---
## Participant Criteria
### Target Participants
| Criterion | Requirement |
|-----------|------------|
| **User type** | [e.g., Active users, churned users, prospects] |
| **Role/title** | [e.g., Product managers, developers] |
| **Experience level** | [e.g., 1+ years using similar products] |
| **Company size** | [e.g., 50-500 employees] |
| **Geography** | [e.g., US-based, English-speaking] |
### Screening Questions
1. [Question to verify participant meets criteria]
2. [Question to verify participant meets criteria]
3. [Question to ensure diversity of perspectives]
### Exclusion Criteria
- [e.g., Current employees or family of employees]
- [e.g., Participants in a study within the last 6 months]
### Sample Size
- **Target:** [Number] participants
- **Justification:** [e.g., "5 participants identify ~80% of usability issues" or "Statistical significance requires N=200 for survey"]
---
## Recruitment Plan
| Channel | Target Count | Timeline | Incentive |
|---------|-------------|----------|-----------|
| [Customer database] | [N] | [Dates] | [$Amount or type] |
| [User panel] | [N] | [Dates] | [$Amount or type] |
| [Social media] | [N] | [Dates] | [$Amount or type] |
### Incentive
- **Amount:** [$X per session or equivalent]
- **Form:** [Gift card, account credit, donation to charity]
- **Distribution:** [Immediately after session / within 5 business days]
---
## Interview / Test Guide
### Introduction (5 minutes)
- Welcome and thank participant
- Explain purpose (learning, not testing them)
- Confirm consent and recording permission
- Set expectations for session duration
### Warm-Up Questions (5 minutes)
1. [Background question about their role/context]
2. [Question about current workflow/tools]
### Core Tasks / Questions (30-40 minutes)
**Task 1:** [Description of task or topic area]
- [Specific prompt or scenario]
- [Follow-up probes]
**Task 2:** [Description of task or topic area]
- [Specific prompt or scenario]
- [Follow-up probes]
**Task 3:** [Description of task or topic area]
- [Specific prompt or scenario]
- [Follow-up probes]
### Wrap-Up (5 minutes)
- Overall impressions
- Anything we did not ask about that they want to share
- Thank participant and explain next steps
---
## Analysis Framework
### Data Collection
- [ ] Session recordings stored securely
- [ ] Notes taken during each session
- [ ] Observations tagged by research question
### Analysis Method
- **Affinity mapping:** Group observations into themes
- **Task success rate:** [For usability tests] Completion rate per task
- **Severity rating:** [For issues] Critical / Major / Minor / Cosmetic
- **Quantitative analysis:** [For surveys] Statistical analysis plan
### Synthesis Approach
1. Review all session notes and recordings
2. Identify patterns and themes across participants
3. Map findings to research questions
4. Prioritize findings by impact and frequency
5. Develop actionable recommendations
---
## Timeline
| Phase | Dates | Activities |
|-------|-------|-----------|
| Planning | [Week 1] | Finalize plan, create guide, prepare materials |
| Recruitment | [Week 1-2] | Screen and schedule participants |
| Fieldwork | [Week 2-3] | Conduct sessions |
| Analysis | [Week 3-4] | Synthesize findings |
| Reporting | [Week 4] | Create report, present to stakeholders |
---
## Deliverables
- [ ] Research findings report (key insights, evidence, recommendations)
- [ ] Presentation deck for stakeholders
- [ ] Highlight reel of key moments (if recorded)
- [ ] Actionable recommendations prioritized by impact
- [ ] Raw data archive (notes, recordings) stored per data policy

59
project-management/CLAUDE.md
View File

@@ -1,17 +1,20 @@
# Project Management Skills - Claude Code Guidance # Project Management Skills - Claude Code Guidance
This guide covers the 6 production-ready project management skills with Atlassian MCP integration. This guide covers the 6 production-ready project management skills, 12 Python automation tools, and Atlassian MCP integration.
## PM Skills Overview ## PM Skills Overview
**Available Skills:** **Available Skills:**
1. **senior-pm/** - Senior project manager workflows and best practices 1. **senior-pm/** - Portfolio health, risk analysis, resource planning (3 scripts)
2. **scrum-master/** - Scrum ceremonies, agile coaching, team facilitation 2. **scrum-master/** - Sprint health, velocity forecasting, retrospectives (3 scripts)
3. **jira-expert/** - Jira administration, workflows, automation 3. **jira-expert/** - JQL building, workflow validation (2 scripts)
4. **confluence-expert/** - Documentation, knowledge management, collaboration 4. **confluence-expert/** - Space structure, content auditing (2 scripts)
5. **atlassian-admin/** - Atlassian suite administration and configuration 5. **atlassian-admin/** - Permission auditing (1 script)
6. **atlassian-templates/** - Ready-to-use templates for Jira and Confluence 6. **atlassian-templates/** - Template scaffolding (1 script)
**Total Tools:** 12 Python automation tools
**Agent:** cs-project-manager (orchestrates all 6 skills)
**Slash Commands:** 3 (/sprint-health, /project-health, /retro)
**Key Feature:** Atlassian MCP Server integration for direct Jira/Confluence operations **Key Feature:** Atlassian MCP Server integration for direct Jira/Confluence operations
## Atlassian MCP Integration ## Atlassian MCP Integration
@@ -62,6 +65,10 @@ mcp__atlassian__create_page space="TEAM" title="Sprint Retrospective"
**Focus:** Jira configuration, custom workflows, automation rules **Focus:** Jira configuration, custom workflows, automation rules
**Scripts:**
- `scripts/jql_query_builder.py` — Pattern-matching JQL builder from natural language
- `scripts/workflow_validator.py` — Validates workflow definitions for anti-patterns
**Key Workflows:** **Key Workflows:**
- Workflow customization - Workflow customization
- Automation rule creation - Automation rule creation
@@ -72,6 +79,10 @@ mcp__atlassian__create_page space="TEAM" title="Sprint Retrospective"
**Focus:** Documentation strategy, templates, knowledge management **Focus:** Documentation strategy, templates, knowledge management
**Scripts:**
- `scripts/space_structure_generator.py` — Generates space hierarchy from team description
- `scripts/content_audit_analyzer.py` — Analyzes page inventory for stale/orphaned content
**Key Workflows:** **Key Workflows:**
- Space architecture design - Space architecture design
- Template library creation - Template library creation
@@ -82,6 +93,9 @@ mcp__atlassian__create_page space="TEAM" title="Sprint Retrospective"
**Focus:** Suite administration, user management, integrations **Focus:** Suite administration, user management, integrations
**Scripts:**
- `scripts/permission_audit_tool.py` — Analyzes permission schemes for security gaps
**Key Workflows:** **Key Workflows:**
- User provisioning and permissions - User provisioning and permissions
- SSO/SAML configuration - SSO/SAML configuration
@@ -92,6 +106,9 @@ mcp__atlassian__create_page space="TEAM" title="Sprint Retrospective"
**Focus:** Ready-to-use templates for common PM tasks **Focus:** Ready-to-use templates for common PM tasks
**Scripts:**
- `scripts/template_scaffolder.py` — Generates Confluence storage-format XHTML templates
**Available Templates:** **Available Templates:**
- Sprint planning template - Sprint planning template
- Retrospective formats (Start-Stop-Continue, 4Ls, Mad-Sad-Glad) - Retrospective formats (Start-Stop-Continue, 4Ls, Mad-Sad-Glad)
@@ -124,6 +141,30 @@ mcp__atlassian__create_page space="DOCS" title="Feature Spec" template="feature-
mcp__atlassian__link_issue issue="PROJ-123" confluence_page_id="456789" mcp__atlassian__link_issue issue="PROJ-123" confluence_page_id="456789"
``` ```
## Python Automation Tools
### New Scripts (Phase 2)
```bash
# JQL from natural language
python jira-expert/scripts/jql_query_builder.py "high priority bugs assigned to me"
# Validate Jira workflow
python jira-expert/scripts/workflow_validator.py workflow.json
# Generate Confluence space structure
python confluence-expert/scripts/space_structure_generator.py team_info.json
# Audit Confluence content health
python confluence-expert/scripts/content_audit_analyzer.py pages.json
# Audit Atlassian permissions
python atlassian-admin/scripts/permission_audit_tool.py permissions.json
# Scaffold Confluence templates
python atlassian-templates/scripts/template_scaffolder.py meeting-notes
```
## Additional Resources ## Additional Resources
- **Installation Guide:** `INSTALLATION_GUIDE.txt` - **Installation Guide:** `INSTALLATION_GUIDE.txt`
@@ -134,6 +175,8 @@ mcp__atlassian__link_issue issue="PROJ-123" confluence_page_id="456789"
--- ---
**Last Updated:** November 5, 2025 **Last Updated:** March 9, 2026
**Skills Deployed:** 6/6 PM skills production-ready **Skills Deployed:** 6/6 PM skills production-ready
**Total Tools:** 12 Python automation tools
**Agent:** cs-project-manager | **Commands:** 3
**Integration:** Atlassian MCP Server for Jira/Confluence automation **Integration:** Atlassian MCP Server for Jira/Confluence automation

173
project-management/atlassian-admin/assets/permission_scheme_template.json Normal file
View File

@@ -0,0 +1,173 @@
{
"permissionScheme": {
"name": "Standard Project Permission Scheme",
"description": "Default permission scheme for standard projects. Assigns permissions based on project roles.",
"version": "1.0",
"lastUpdated": "YYYY-MM-DD",
"owner": "IT Admin Team"
},
"roles": {
"projectAdmin": {
"description": "Full project administration including configuration and user management",
"typicalGroups": ["project-leads", "engineering-managers"]
},
"developer": {
"description": "Create and manage issues, transitions, and attachments",
"typicalGroups": ["dept-engineering", "dept-product"]
},
"user": {
"description": "View issues, add comments, and create basic issues",
"typicalGroups": ["org-all-employees"]
},
"viewer": {
"description": "Read-only access to project issues and boards",
"typicalGroups": ["stakeholders", "external-contractors"]
}
},
"permissions": {
"project": {
"ADMINISTER_PROJECTS": {
"description": "Manage project settings, roles, and permissions",
"grantedTo": ["projectAdmin"]
},
"BROWSE_PROJECTS": {
"description": "View the project and its issues",
"grantedTo": ["projectAdmin", "developer", "user", "viewer"]
},
"VIEW_DEV_TOOLS": {
"description": "View development panel (commits, branches, PRs)",
"grantedTo": ["projectAdmin", "developer"]
},
"VIEW_READONLY_WORKFLOW": {
"description": "View read-only workflow",
"grantedTo": ["projectAdmin", "developer", "user", "viewer"]
}
},
"issues": {
"CREATE_ISSUES": {
"description": "Create new issues in the project",
"grantedTo": ["projectAdmin", "developer", "user"]
},
"EDIT_ISSUES": {
"description": "Edit issue fields",
"grantedTo": ["projectAdmin", "developer"]
},
"DELETE_ISSUES": {
"description": "Delete issues permanently",
"grantedTo": ["projectAdmin"]
},
"ASSIGN_ISSUES": {
"description": "Assign issues to team members",
"grantedTo": ["projectAdmin", "developer"]
},
"ASSIGNABLE_USER": {
"description": "Be assigned to issues",
"grantedTo": ["projectAdmin", "developer"]
},
"CLOSE_ISSUES": {
"description": "Close/resolve issues",
"grantedTo": ["projectAdmin", "developer"]
},
"RESOLVE_ISSUES": {
"description": "Set issue resolution",
"grantedTo": ["projectAdmin", "developer"]
},
"TRANSITION_ISSUES": {
"description": "Transition issues through workflow",
"grantedTo": ["projectAdmin", "developer", "user"]
},
"LINK_ISSUES": {
"description": "Create and remove issue links",
"grantedTo": ["projectAdmin", "developer"]
},
"MOVE_ISSUES": {
"description": "Move issues between projects",
"grantedTo": ["projectAdmin"]
},
"SCHEDULE_ISSUES": {
"description": "Set due dates on issues",
"grantedTo": ["projectAdmin", "developer"]
},
"SET_ISSUE_SECURITY": {
"description": "Set security level on issues",
"grantedTo": ["projectAdmin"]
}
},
"comments": {
"ADD_COMMENTS": {
"description": "Add comments to issues",
"grantedTo": ["projectAdmin", "developer", "user"]
},
"EDIT_ALL_COMMENTS": {
"description": "Edit any comment",
"grantedTo": ["projectAdmin"]
},
"EDIT_OWN_COMMENTS": {
"description": "Edit own comments",
"grantedTo": ["projectAdmin", "developer", "user"]
},
"DELETE_ALL_COMMENTS": {
"description": "Delete any comment",
"grantedTo": ["projectAdmin"]
},
"DELETE_OWN_COMMENTS": {
"description": "Delete own comments",
"grantedTo": ["projectAdmin", "developer", "user"]
}
},
"attachments": {
"CREATE_ATTACHMENTS": {
"description": "Attach files to issues",
"grantedTo": ["projectAdmin", "developer", "user"]
},
"DELETE_ALL_ATTACHMENTS": {
"description": "Delete any attachment",
"grantedTo": ["projectAdmin"]
},
"DELETE_OWN_ATTACHMENTS": {
"description": "Delete own attachments",
"grantedTo": ["projectAdmin", "developer", "user"]
}
},
"worklogs": {
"WORK_ON_ISSUES": {
"description": "Log work on issues",
"grantedTo": ["projectAdmin", "developer"]
},
"EDIT_ALL_WORKLOGS": {
"description": "Edit any worklog",
"grantedTo": ["projectAdmin"]
},
"EDIT_OWN_WORKLOGS": {
"description": "Edit own worklogs",
"grantedTo": ["projectAdmin", "developer"]
},
"DELETE_ALL_WORKLOGS": {
"description": "Delete any worklog",
"grantedTo": ["projectAdmin"]
},
"DELETE_OWN_WORKLOGS": {
"description": "Delete own worklogs",
"grantedTo": ["projectAdmin", "developer"]
}
}
},
"projectMappings": [
{
"projectKey": "EXAMPLE",
"projectName": "Example Project",
"scheme": "Standard Project Permission Scheme",
"roleAssignments": {
"projectAdmin": ["project-leads"],
"developer": ["team-example-devs"],
"user": ["org-all-employees"],
"viewer": ["stakeholders-example"]
}
}
],
"notes": {
"usage": "Copy this template and customize role assignments per project. Use group names that match your Atlassian groups.",
"review": "Review permission scheme assignments quarterly as part of access review.",
"changes": "Any changes to permission schemes should be documented and approved by IT Admin."
}
}

214
project-management/atlassian-admin/references/security-hardening-guide.md Normal file
View File

@@ -0,0 +1,214 @@
# Atlassian Cloud Security Hardening Guide
## Overview
This guide provides a comprehensive security hardening checklist for Atlassian Cloud products (Jira, Confluence, Bitbucket). It covers identity management, access controls, data protection, and monitoring practices aligned with enterprise security standards.
## Identity & Authentication
### SSO / SAML Setup
**Implementation Steps:**
1. Verify your domain in Atlassian Admin (admin.atlassian.com)
2. Claim all company email accounts
3. Configure SAML SSO with your identity provider (Okta, Azure AD, Google Workspace)
4. Set authentication policy to enforce SSO for all managed accounts
5. Test with a pilot group before full rollout
6. Disable password-based login for managed accounts
**Configuration Checklist:**
- [ ] Domain verified and accounts claimed
- [ ] SAML IdP configured with correct entity ID and SSO URL
- [ ] Attribute mapping: email, displayName, groups
- [ ] Single Logout (SLO) configured
- [ ] Authentication policy enforcing SSO
- [ ] Fallback access configured for emergency admin accounts
- [ ] SCIM provisioning enabled for automatic user sync
### Two-Factor Authentication (2FA)
**Enforcement Policy:**
- [ ] 2FA required for all managed accounts
- [ ] Enforce via authentication policy (not just recommended)
- [ ] Hardware security keys (FIDO2/WebAuthn) preferred for admin accounts
- [ ] TOTP (authenticator app) as minimum for all users
- [ ] SMS-based 2FA disabled (SIM swap vulnerability)
- [ ] Recovery codes generated and stored securely
### Session Management
- [ ] Session timeout set to 8 hours of inactivity (maximum)
- [ ] Absolute session timeout: 24 hours
- [ ] Require re-authentication for sensitive operations
- [ ] Monitor concurrent sessions per user
- [ ] Enforce session termination on password change
## Access Controls
### IP Allowlisting
**Configuration:**
- [ ] Enable IP allowlisting for organization
- [ ] Add corporate office IP ranges
- [ ] Add VPN exit node IP addresses
- [ ] Add CI/CD server IPs for API access
- [ ] Test access from all approved locations
- [ ] Document approved IP ranges with justification
- [ ] Review IP allowlist quarterly
**Exceptions:**
- Mobile access may require VPN or MDM solution
- Remote workers need VPN or conditional access policies
- API integrations need stable IP ranges
### API Token Management
**Policies:**
- [ ] Inventory all API tokens in use
- [ ] Set maximum token lifetime (90 days recommended)
- [ ] Require token rotation on schedule
- [ ] Use service accounts for integrations (not personal tokens)
- [ ] Monitor API token usage patterns
- [ ] Revoke tokens immediately on employee departure
- [ ] Document purpose and owner for each token
**Best Practices:**
- Use OAuth 2.0 (3LO) for user-context integrations
- Use API tokens only for service-to-service
- Store tokens in secrets management (never in code)
- Implement least-privilege scopes for OAuth apps
### Permission Model
- [ ] Review global permissions quarterly
- [ ] Use groups for permission assignment (not individual users)
- [ ] Implement role-based access for Jira projects
- [ ] Restrict Confluence space admin to designated owners
- [ ] Limit Jira system admin to 2-3 people
- [ ] Audit "anyone" or "logged in users" permissions
- [ ] Remove direct user permissions where groups exist
## Audit & Monitoring
### Audit Log Configuration
**What to Monitor:**
- User authentication events (login, logout, failed attempts)
- Permission changes (project, space, global)
- User account changes (creation, deactivation, group changes)
- API token creation and revocation
- App installations and updates
- Data export operations
- Admin configuration changes
**Setup Steps:**
- [ ] Enable organization audit log
- [ ] Configure audit log retention (minimum 1 year)
- [ ] Set up automated export to SIEM (Splunk, Datadog, etc.)
- [ ] Create alerts for suspicious patterns
- [ ] Schedule monthly audit log review
- [ ] Document incident response procedures for alerts
### Alerting Rules
**Critical Alerts (Immediate Response):**
- Multiple failed login attempts (>5 in 10 minutes)
- Admin permission grants to unexpected users
- API token created by non-service accounts
- Bulk data export or deletion
- New third-party app installed with broad permissions
**Warning Alerts (Same-Day Review):**
- New admin users added
- Permission scheme changes
- Authentication policy modifications
- IP allowlist changes
- User deactivation (verify it is expected)
## Data Protection
### Data Residency
- [ ] Configure data residency realm (US, EU, AU, etc.)
- [ ] Verify product data pinned to selected region
- [ ] Document data residency for compliance audits
- [ ] Review data residency coverage (some metadata may be global)
- [ ] Monitor for new residency options from Atlassian
### Encryption
- [ ] Verify encryption at rest (AES-256, managed by Atlassian)
- [ ] Verify encryption in transit (TLS 1.2+)
- [ ] Review Atlassian's encryption key management practices
- [ ] Consider BYOK (Bring Your Own Key) for Atlassian Guard Premium
### Data Loss Prevention
- [ ] Configure content restrictions for sensitive pages/issues
- [ ] Implement classification labels (public, internal, confidential)
- [ ] Restrict file attachment types if needed
- [ ] Monitor bulk exports and downloads
- [ ] Set up DLP rules for sensitive data patterns (PII, credentials)
## Mobile Device Management
### Mobile Access Controls
- [ ] Require MDM enrollment for mobile Atlassian apps
- [ ] Enforce device encryption
- [ ] Require screen lock with biometrics or PIN
- [ ] Enable remote wipe capability
- [ ] Block rooted/jailbroken devices
- [ ] Restrict copy/paste to managed apps
- [ ] Set app-level PIN for Atlassian apps
### Mobile Policies
- [ ] Define approved mobile devices/OS versions
- [ ] Enforce automatic app updates
- [ ] Configure offline data access limits
- [ ] Set maximum offline cache duration
- [ ] Review mobile access logs monthly
## Third-Party App Security
### App Review Process
- [ ] Maintain approved app list (whitelist)
- [ ] Review app permissions before installation
- [ ] Verify app is Atlassian Marketplace certified
- [ ] Check app vendor security certifications
- [ ] Assess data access scope (read-only vs read-write)
- [ ] Review app privacy policy
- [ ] Document app owner and business justification
### App Governance
- [ ] Audit installed apps quarterly
- [ ] Remove unused apps (no usage in 90 days)
- [ ] Monitor app permission changes
- [ ] Restrict app installation to admins only
- [ ] Review Atlassian Guard app access policies
- [ ] Set up alerts for new app installations
## Compliance Documentation
### Required Documentation
- [ ] Security policy for Atlassian Cloud usage
- [ ] Access control matrix (roles, permissions, justification)
- [ ] Incident response plan for Atlassian security events
- [ ] Data classification policy applied to Atlassian content
- [ ] Third-party app risk assessments
- [ ] Annual security review report
### Compliance Frameworks
- **SOC 2:** Map Atlassian controls to Trust Service Criteria
- **ISO 27001:** Align with Annex A controls for cloud services
- **GDPR:** Configure data residency, right to deletion, DPAs
- **HIPAA:** Review BAA availability, encryption, access controls
## Hardening Schedule
| Task | Frequency | Owner |
|------|-----------|-------|
| Permission audit | Quarterly | IT Admin |
| API token rotation | Every 90 days | Integration owners |
| App review | Quarterly | IT Admin |
| Audit log review | Monthly | Security team |
| IP allowlist review | Quarterly | IT Admin |
| Authentication policy review | Semi-annually | Security team |
| Full security assessment | Annually | Security team |
| User access review | Quarterly | Managers + IT Admin |
| Data residency verification | Annually | Compliance |
| Mobile device audit | Quarterly | IT Admin |

177
project-management/atlassian-admin/references/user-provisioning-checklist.md Normal file
View File

@@ -0,0 +1,177 @@
# User Provisioning & Lifecycle Management Checklist
## Overview
This checklist covers the complete user lifecycle in Atlassian Cloud products, from onboarding through offboarding. Consistent provisioning ensures security, compliance, and a smooth user experience.
## Onboarding Steps
### Pre-Provisioning
- [ ] Receive approved access request (ticket or HR system trigger)
- [ ] Verify employee record in HR system
- [ ] Determine role-based access level (see Role Templates below)
- [ ] Identify required Atlassian products (Jira, Confluence, Bitbucket)
- [ ] Identify required project/space access
### Account Creation
- [ ] User account auto-provisioned via SCIM (preferred) or manually created
- [ ] Email domain matches verified organization domain
- [ ] SSO authentication verified (user can log in via IdP)
- [ ] 2FA enrollment confirmed
- [ ] Correct product access assigned (Jira, Confluence, Bitbucket)
### Group Membership
- [ ] Add to organization-level groups (e.g., `all-employees`)
- [ ] Add to department group (e.g., `engineering`, `product`, `marketing`)
- [ ] Add to team-specific groups (e.g., `team-platform`, `team-mobile`)
- [ ] Add to project groups as needed (e.g., `project-alpha-members`)
- [ ] Verify group membership grants correct permissions
### Product Configuration
- [ ] **Jira:** Add to correct project roles (Developer, User, Admin)
- [ ] **Jira:** Assign to correct board(s)
- [ ] **Jira:** Set default dashboard if applicable
- [ ] **Confluence:** Grant access to relevant spaces
- [ ] **Confluence:** Add to space groups with appropriate permission level
- [ ] **Bitbucket:** Grant repository access per team
- [ ] **Bitbucket:** Configure branch permissions
### Welcome & Training
- [ ] Send welcome email with access details and key links
- [ ] Share Confluence onboarding page (getting started guide)
- [ ] Assign onboarding buddy for Atlassian tool questions
- [ ] Schedule optional training session for new users
- [ ] Provide link to internal Atlassian usage guidelines
## Role-Based Access Templates
### Developer
- **Jira:** Project Developer role (create, edit, transition issues)
- **Confluence:** Team space editor, documentation spaces viewer
- **Bitbucket:** Repository write access for team repos
### Product Manager
- **Jira:** Project Admin role (manage boards, workflows, components)
- **Confluence:** Product spaces editor, all team spaces viewer
- **Bitbucket:** Repository read access (optional)
### Designer
- **Jira:** Project User role (view, comment, transition)
- **Confluence:** Design space editor, product spaces editor
- **Bitbucket:** No access (unless needed)
### Engineering Manager
- **Jira:** Project Admin for managed projects, viewer for others
- **Confluence:** Team space admin, all spaces viewer
- **Bitbucket:** Repository admin for team repos
### Executive / Stakeholder
- **Jira:** Viewer role on strategic projects, dashboard access
- **Confluence:** Viewer on relevant spaces
- **Bitbucket:** No access
### Contractor / External
- **Jira:** Project User role, limited to specific projects
- **Confluence:** Viewer on specific spaces only (no edit)
- **Bitbucket:** Repository read access, specific repos only
- **Additional:** Set account expiration date, restrict IP access
## Group Membership Standards
### Naming Convention
```
org-{company} # Organization-wide groups
dept-{department} # Department groups
team-{team-name} # Team-specific groups
project-{project} # Project-scoped groups
role-{role} # Role-based groups (role-admin, role-viewer)
```
### Standard Groups
| Group | Purpose | Products |
|-------|---------|----------|
| `org-all-employees` | All full-time employees | Jira, Confluence |
| `dept-engineering` | All engineers | Jira, Confluence, Bitbucket |
| `dept-product` | All product team | Jira, Confluence |
| `dept-marketing` | All marketing team | Confluence |
| `role-jira-admins` | Jira administrators | Jira |
| `role-confluence-admins` | Confluence administrators | Confluence |
| `role-org-admins` | Organization administrators | All |
## Offboarding Procedure
### Immediate Actions (Day of Departure)
- [ ] Deactivate user account in Atlassian (or via IdP/SCIM)
- [ ] Revoke all API tokens associated with the user
- [ ] Revoke all OAuth app authorizations
- [ ] Transfer ownership of critical Confluence pages
- [ ] Reassign Jira issues (open/in-progress items)
- [ ] Remove from all groups
- [ ] Document access removal in offboarding ticket
### Within 24 Hours
- [ ] Verify account is fully deactivated (cannot log in)
- [ ] Check for shared credentials or service accounts
- [ ] Review audit log for recent activity
- [ ] Transfer Confluence space ownership if applicable
- [ ] Update Jira project leads/component leads if applicable
- [ ] Remove from any Atlassian Marketplace vendor accounts
### Within 7 Days
- [ ] Verify no lingering sessions or cached access
- [ ] Review integrations the user may have set up
- [ ] Check for automation rules owned by the user
- [ ] Update team dashboards and filters
- [ ] Confirm with manager that all transfers are complete
### Data Retention
- [ ] User content (pages, issues, comments) retained per policy
- [ ] Personal spaces archived or transferred
- [ ] Account marked as deactivated (not deleted) for audit trail
- [ ] Data deletion request processed if required (GDPR)
## Quarterly Access Reviews
### Review Process
1. Generate user access report from Atlassian Admin
2. Distribute to managers for team verification
3. Managers confirm or flag each user's access level
4. IT Admin processes approved changes
5. Document review completion for compliance
### Review Checklist
- [ ] All active accounts match current employee list
- [ ] No accounts for departed employees
- [ ] Group memberships align with current roles
- [ ] Admin access limited to approved administrators
- [ ] External/contractor accounts have valid expiration dates
- [ ] Service accounts documented with current owners
- [ ] Unused accounts (no login in 90 days) flagged for review
### Compliance Documentation
- [ ] Access review completion date recorded
- [ ] Manager sign-off captured (email or ticket)
- [ ] Changes made during review documented
- [ ] Exceptions documented with justification and approval
- [ ] Report filed for audit purposes
- [ ] Next review date scheduled
## Automation Opportunities
### SCIM Provisioning
- Automatically create/deactivate accounts based on IdP changes
- Sync group membership from IdP groups
- Reduce manual provisioning errors
- Ensure immediate deactivation on termination
### Workflow Automation
- Trigger onboarding checklist from HR system event
- Auto-assign to groups based on department/role attributes
- Send welcome messages via Confluence automation
- Schedule access reviews via Jira recurring tickets
### Monitoring
- Alert on accounts without 2FA after 7 days
- Alert on admin group changes
- Weekly report of new and deactivated accounts
- Monthly stale account report (no login in 90 days)

469
project-management/atlassian-admin/scripts/permission_audit_tool.py Normal file
View File

@@ -0,0 +1,469 @@
#!/usr/bin/env python3
"""
Permission Audit Tool
Analyzes Atlassian permission schemes for security issues. Checks for
over-permissioned groups, direct user permissions, missing restrictions on
sensitive actions, inconsistencies across projects, and compliance gaps.
Usage:
python permission_audit_tool.py permissions.json
python permission_audit_tool.py permissions.json --format json
"""
import argparse
import json
import sys
from typing import Any, Dict, List, Optional, Set
# ---------------------------------------------------------------------------
# Audit Configuration
# ---------------------------------------------------------------------------
SENSITIVE_PERMISSIONS = {
"administer_project",
"administer_jira",
"delete_issues",
"delete_all_comments",
"delete_all_attachments",
"manage_watchers",
"modify_reporter",
"bulk_change",
"system_admin",
"manage_group_filter_subscriptions",
}
RECOMMENDED_GROUP_ONLY_PERMISSIONS = {
"browse_projects",
"create_issues",
"edit_issues",
"transition_issues",
"assign_issues",
"resolve_issues",
"close_issues",
"add_comments",
"edit_all_comments",
}
SEVERITY_WEIGHTS = {
"critical": 25,
"high": 15,
"medium": 8,
"low": 3,
"info": 1,
}
# ---------------------------------------------------------------------------
# Audit Checks
# ---------------------------------------------------------------------------
def check_over_permissioned_groups(
schemes: List[Dict[str, Any]],
) -> List[Dict[str, str]]:
"""Check for groups with overly broad admin access."""
findings = []
for scheme in schemes:
scheme_name = scheme.get("name", "Unknown Scheme")
grants = scheme.get("grants", [])
group_permissions = {}
for grant in grants:
group = grant.get("group", "")
permission = grant.get("permission", "").lower()
if group:
if group not in group_permissions:
group_permissions[group] = set()
group_permissions[group].add(permission)
for group, perms in group_permissions.items():
admin_perms = perms & SENSITIVE_PERMISSIONS
if len(admin_perms) >= 3:
findings.append({
"rule": "over_permissioned_group",
"severity": "high",
"scheme": scheme_name,
"group": group,
"message": f"Group '{group}' has {len(admin_perms)} sensitive permissions "
f"in scheme '{scheme_name}': {', '.join(sorted(admin_perms))}. "
f"Review if all are necessary.",
})
if "system_admin" in perms or "administer_jira" in perms:
findings.append({
"rule": "admin_access_warning",
"severity": "critical",
"scheme": scheme_name,
"group": group,
"message": f"Group '{group}' has system/Jira admin access in '{scheme_name}'. "
f"Ensure this is strictly necessary and membership is limited.",
})
return findings
def check_direct_user_permissions(
schemes: List[Dict[str, Any]],
) -> List[Dict[str, str]]:
"""Check for permissions granted directly to users instead of groups."""
findings = []
for scheme in schemes:
scheme_name = scheme.get("name", "Unknown Scheme")
grants = scheme.get("grants", [])
for grant in grants:
user = grant.get("user", "")
permission = grant.get("permission", "")
if user and not grant.get("group"):
severity = "high" if permission.lower() in SENSITIVE_PERMISSIONS else "medium"
findings.append({
"rule": "direct_user_permission",
"severity": severity,
"scheme": scheme_name,
"user": user,
"message": f"User '{user}' has direct permission '{permission}' in '{scheme_name}'. "
f"Use groups instead for maintainability and audit clarity.",
})
return findings
def check_missing_restrictions(
schemes: List[Dict[str, Any]],
) -> List[Dict[str, str]]:
"""Check for missing restrictions on sensitive actions."""
findings = []
for scheme in schemes:
scheme_name = scheme.get("name", "Unknown Scheme")
grants = scheme.get("grants", [])
granted_permissions = set()
for grant in grants:
granted_permissions.add(grant.get("permission", "").lower())
# Check if delete permissions are unrestricted
delete_perms = {"delete_issues", "delete_all_comments", "delete_all_attachments"}
unrestricted_deletes = delete_perms & granted_permissions
for grant in grants:
perm = grant.get("permission", "").lower()
group = grant.get("group", "")
if perm in delete_perms and group:
# Check if granted to broad groups
broad_groups = {"users", "everyone", "all-users", "jira-users", "jira-software-users"}
if group.lower() in broad_groups:
findings.append({
"rule": "unrestricted_delete",
"severity": "critical",
"scheme": scheme_name,
"message": f"Delete permission '{perm}' granted to broad group '{group}' "
f"in '{scheme_name}'. Restrict to admins or leads only.",
})
# Check if admin permissions exist
admin_perms = {"administer_project", "administer_jira", "system_admin"}
if not (admin_perms & granted_permissions):
findings.append({
"rule": "no_admin_defined",
"severity": "medium",
"scheme": scheme_name,
"message": f"No explicit admin permission defined in '{scheme_name}'. "
f"Ensure project administration is properly assigned.",
})
return findings
def check_scheme_consistency(
schemes: List[Dict[str, Any]],
) -> List[Dict[str, str]]:
"""Check for inconsistencies across permission schemes."""
findings = []
if len(schemes) < 2:
return findings
# Compare permission sets across schemes
scheme_perms = {}
for scheme in schemes:
name = scheme.get("name", "Unknown")
perms = set()
for grant in scheme.get("grants", []):
perms.add(grant.get("permission", "").lower())
scheme_perms[name] = perms
# Find schemes with significantly different permission sets
all_perms = set()
for perms in scheme_perms.values():
all_perms |= perms
scheme_names = list(scheme_perms.keys())
for i in range(len(scheme_names)):
for j in range(i + 1, len(scheme_names)):
name_a = scheme_names[i]
name_b = scheme_names[j]
diff = scheme_perms[name_a].symmetric_difference(scheme_perms[name_b])
if len(diff) > 5:
findings.append({
"rule": "scheme_inconsistency",
"severity": "medium",
"message": f"Schemes '{name_a}' and '{name_b}' differ significantly "
f"({len(diff)} different permissions). Review for intentional differences.",
})
return findings
def check_compliance_gaps(
schemes: List[Dict[str, Any]],
) -> List[Dict[str, str]]:
"""Check for common compliance gaps."""
findings = []
for scheme in schemes:
scheme_name = scheme.get("name", "Unknown Scheme")
grants = scheme.get("grants", [])
groups_used = set()
users_used = set()
for grant in grants:
if grant.get("group"):
groups_used.add(grant["group"])
if grant.get("user"):
users_used.add(grant["user"])
# Check for separation of duties
admin_groups = set()
for grant in grants:
if grant.get("permission", "").lower() in SENSITIVE_PERMISSIONS and grant.get("group"):
admin_groups.add(grant["group"])
if len(admin_groups) == 1 and len(groups_used) > 1:
findings.append({
"rule": "separation_of_duties",
"severity": "info",
"scheme": scheme_name,
"message": f"Only one group ('{next(iter(admin_groups))}') holds all sensitive permissions "
f"in '{scheme_name}'. Consider separating duties across multiple groups.",
})
# Check user count
if len(users_used) > 5:
findings.append({
"rule": "too_many_direct_users",
"severity": "high",
"scheme": scheme_name,
"message": f"Scheme '{scheme_name}' has {len(users_used)} direct user grants. "
f"Migrate to group-based permissions for better governance.",
})
return findings
# ---------------------------------------------------------------------------
# Main Analysis
# ---------------------------------------------------------------------------
def audit_permissions(data: Dict[str, Any]) -> Dict[str, Any]:
"""Run full permission audit."""
schemes = data.get("schemes", [])
if not schemes:
# Try treating the entire input as a single scheme
if data.get("grants") or data.get("name"):
schemes = [data]
else:
return {
"risk_score": 0,
"grade": "invalid",
"error": "No permission schemes found in input",
"findings": [],
"summary": {},
}
all_findings = []
all_findings.extend(check_over_permissioned_groups(schemes))
all_findings.extend(check_direct_user_permissions(schemes))
all_findings.extend(check_missing_restrictions(schemes))
all_findings.extend(check_scheme_consistency(schemes))
all_findings.extend(check_compliance_gaps(schemes))
# Calculate risk score (higher = more risk)
summary = {"critical": 0, "high": 0, "medium": 0, "low": 0, "info": 0}
total_penalty = 0
for finding in all_findings:
severity = finding["severity"]
summary[severity] = summary.get(severity, 0) + 1
total_penalty += SEVERITY_WEIGHTS.get(severity, 0)
risk_score = min(100, total_penalty)
health_score = max(0, 100 - risk_score)
if health_score >= 85:
grade = "excellent"
elif health_score >= 70:
grade = "good"
elif health_score >= 50:
grade = "fair"
else:
grade = "poor"
# Generate remediation recommendations
remediations = _generate_remediations(all_findings)
return {
"risk_score": risk_score,
"health_score": health_score,
"grade": grade,
"schemes_analyzed": len(schemes),
"findings": all_findings,
"summary": summary,
"remediations": remediations,
}
def _generate_remediations(findings: List[Dict[str, str]]) -> List[str]:
"""Generate remediation recommendations."""
remediations = []
rules_seen = set()
for finding in findings:
rule = finding["rule"]
if rule in rules_seen:
continue
rules_seen.add(rule)
if rule == "over_permissioned_group":
remediations.append("Review and reduce sensitive permissions for over-permissioned groups. Apply principle of least privilege.")
elif rule == "admin_access_warning":
remediations.append("Audit admin group membership. Limit system/Jira admin access to essential personnel only.")
elif rule == "direct_user_permission":
remediations.append("Migrate direct user permissions to group-based grants. Create functional groups for common permission sets.")
elif rule == "unrestricted_delete":
remediations.append("Restrict delete permissions to project admins or leads. Remove from broad user groups.")
elif rule == "scheme_inconsistency":
remediations.append("Standardize permission schemes across projects. Document intentional differences.")
elif rule == "too_many_direct_users":
remediations.append("Create groups for users with direct permissions. This simplifies onboarding/offboarding.")
elif rule == "separation_of_duties":
remediations.append("Consider splitting admin responsibilities across multiple groups for better separation of duties.")
elif rule == "no_admin_defined":
remediations.append("Define explicit admin permissions in each scheme to ensure proper project governance.")
return remediations
# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------
def format_text_output(result: Dict[str, Any]) -> str:
"""Format results as readable text report."""
lines = []
lines.append("=" * 60)
lines.append("PERMISSION AUDIT REPORT")
lines.append("=" * 60)
lines.append("")
if "error" in result:
lines.append(f"ERROR: {result['error']}")
return "\n".join(lines)
lines.append("AUDIT SUMMARY")
lines.append("-" * 30)
lines.append(f"Risk Score: {result['risk_score']}/100 (lower is better)")
lines.append(f"Health Score: {result['health_score']}/100")
lines.append(f"Grade: {result['grade'].title()}")
lines.append(f"Schemes Analyzed: {result['schemes_analyzed']}")
lines.append("")
summary = result.get("summary", {})
lines.append("FINDINGS BY SEVERITY")
lines.append("-" * 30)
lines.append(f"Critical: {summary.get('critical', 0)}")
lines.append(f"High: {summary.get('high', 0)}")
lines.append(f"Medium: {summary.get('medium', 0)}")
lines.append(f"Low: {summary.get('low', 0)}")
lines.append(f"Info: {summary.get('info', 0)}")
lines.append("")
findings = result.get("findings", [])
if findings:
lines.append("DETAILED FINDINGS")
lines.append("-" * 30)
for i, finding in enumerate(findings, 1):
severity = finding["severity"].upper()
lines.append(f"{i}. [{severity}] {finding['message']}")
lines.append(f" Rule: {finding['rule']}")
if finding.get("scheme"):
lines.append(f" Scheme: {finding['scheme']}")
lines.append("")
remediations = result.get("remediations", [])
if remediations:
lines.append("REMEDIATION RECOMMENDATIONS")
lines.append("-" * 30)
for i, rem in enumerate(remediations, 1):
lines.append(f"{i}. {rem}")
return "\n".join(lines)
def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
"""Format results as JSON."""
return result
# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------
def main() -> int:
"""Main CLI entry point."""
parser = argparse.ArgumentParser(
description="Audit Atlassian permission schemes for security issues"
)
parser.add_argument(
"permissions_file",
help="JSON file with permission scheme data",
)
parser.add_argument(
"--format",
choices=["text", "json"],
default="text",
help="Output format (default: text)",
)
args = parser.parse_args()
try:
with open(args.permissions_file, "r") as f:
data = json.load(f)
result = audit_permissions(data)
if args.format == "json":
print(json.dumps(format_json_output(result), indent=2))
else:
print(format_text_output(result))
return 0
except FileNotFoundError:
print(f"Error: File '{args.permissions_file}' not found", file=sys.stderr)
return 1
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON in '{args.permissions_file}': {e}", file=sys.stderr)
return 1
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

234
project-management/atlassian-templates/references/governance-framework.md Normal file
View File

@@ -0,0 +1,234 @@
# Template Governance Framework
## Overview
Operational framework for managing template lifecycle — creation, updates, deprecation, and quality enforcement with concrete thresholds and decision criteria.
## Ownership Model
### Roles
**Template Owner** (1 per template):
- Reviews usage dashboard on the 1st of each quarter
- Archives templates with <5 uses in the past 90 days
- Responds to change requests within 14 calendar days
- Runs quarterly accuracy check: open 3 random pages created from the template, verify content matches current process
- Escalates to committee if change affects >50 users
**Template Steward** (1 per team/domain):
- Runs monthly usage pull: `CQL: type = page AND label = "template-{name}" AND created >= "now-30d"`
- Flags templates where >30% of users delete or heavily modify a section (indicates friction)
- Collects and triages feedback — tags Jira tickets with `template-change` and links to template page
**Template Committee** (3-5 people, for orgs with 20+ templates):
- Meets quarterly (45 min max): reviews new proposals, resolves conflicts, flags duplicates
- Decision rule: approve if template serves >1 team and doesn't duplicate existing template by >60% content overlap
- Publishes quarterly "Template Health" Confluence page with adoption rates and actions taken
### Assignment Matrix
| Template Category | Owner Role | Steward Role |
|------------------|-----------|-------------|
| Engineering templates | Engineering Manager | Senior Engineer |
| Product templates | Head of Product | Senior PM |
| Meeting templates | Operations Lead | EA/Admin |
| Project templates | PMO Lead | Senior PM |
| HR/People templates | HR Director | HR Coordinator |
| Company-wide templates | Operations Lead | Template Committee |
## Approval Workflow
### New Template Proposal
1. **Request** - Submitter creates proposal with:
- Template name and purpose
- Target audience
- Justification (why existing templates are insufficient)
- Draft content
- Proposed owner
2. **Review** - Template owner/committee evaluates:
- Does this duplicate an existing template?
- Is the scope appropriate (not too broad or narrow)?
- Does it follow design standards?
- Is it needed by more than one team?
3. **Pilot** - If approved:
- Deploy to a small group for 2-4 weeks
- Collect feedback on usability and completeness
- Iterate based on feedback
4. **Launch** - After successful pilot:
- Publish to template library
- Announce to relevant teams
- Add to Template Index page
- Train users if needed
5. **Monitor** - Post-launch:
- Track adoption rate (first 30 days)
- Collect initial feedback
- Make quick adjustments if needed
### Template Update Process
1. **Change Request** - Anyone can suggest changes via:
- Comment on the template page
- Jira ticket tagged `template-change`
- Direct message to template owner
2. **Assessment** - Owner evaluates:
- Impact on existing documents using this template
- Alignment with organizational standards
- Effort required for update
3. **Implementation** - Owner or steward:
- Makes changes in a draft version
- Reviews with 1-2 frequent users
- Updates version number and changelog
- Publishes updated template
4. **Communication** - Notify users:
- Post update in relevant Slack/Teams channel
- Update Template Index page
- Send email for major changes
## Change Management
### Impact Categories
**Low Impact (Owner decides):**
- Typo fixes and formatting improvements
- Clarifying existing instructions
- Adding optional sections
**Medium Impact (Owner + 1 reviewer):**
- Adding new required sections
- Changing variable names or structure
- Updating macro usage
**High Impact (Committee review):**
- Removing sections from widely-used templates
- Merging or splitting templates
- Changing organizational template standards
### Communication Plan
| Change Type | Communication | Timeline |
|------------|---------------|----------|
| Low impact | Changelog update | Same day |
| Medium impact | Team channel announcement | 1 week notice |
| High impact | Email + meeting + migration guide | 2-4 weeks notice |
## Deprecation Process
### When to Deprecate
- Template replaced by a better alternative
- Process the template supports has been retired
- Template has zero usage in the past 6 months
- Template is redundant with another active template
### Deprecation Steps
1. **Decision** - Owner proposes deprecation with justification
2. **Announcement** - Notify users 30 days before deprecation:
- Mark template with "DEPRECATED" status
- Add deprecation notice at top of template
- Point to replacement template (if applicable)
3. **Transition Period** - 30 days:
- Template still available but marked deprecated
- New documents should use replacement
- Existing documents do not need to change
4. **Archive** - After transition:
- Move template to Archive section
- Remove from active template list
- Keep accessible for historical reference
5. **Review** - 90 days after archive:
- Confirm no active usage
- Add to annual cleanup list if truly unused
## Usage Tracking
### Metrics & Thresholds
| Metric | Healthy | Flagged | Deprecate |
|--------|---------|---------|-----------|
| Pages created/month | >10 | 3-10 | <3 for 2 consecutive quarters |
| Unique users/month | >5 | 2-5 | 0-1 for 90 days |
| Section deletion rate | <10% | 10-30% | >30% (users removing sections = template mismatch) |
| Time to first use (new templates) | <7 days | 7-30 days | >30 days (failed launch, re-announce or rethink) |
### Tracking via CQL
```
-- Monthly usage for a specific template
type = page AND label = "template-sprint-retro" AND created >= "now-30d"
-- Stale templates (no usage in 90 days)
type = page AND label IN ("template-sprint-retro", "template-decision-log") AND created < "now-90d" AND created >= "now-91d"
-- All template-created pages for audit
type = page AND label = "template-*" ORDER BY created DESC
```
### Reporting
- **Monthly:** Top 10 templates by usage → auto-generated Confluence table
- **Quarterly:** Flag templates below thresholds → owner action required within 14 days
- **Annually:** Full catalog review — archive anything with 0 uses in 6 months
## Quality Standards
### Content Checklist (pass/fail per template)
- [ ] Every section has placeholder text showing expected content (not just a heading)
- [ ] No section references a process, tool, or team that no longer exists
- [ ] All Jira macro JQL filters return results (test quarterly)
- [ ] Links to other Confluence pages resolve (no 404s)
- [ ] Template renders correctly in both desktop and mobile preview
**FAIL examples:** Template says "Update the JIRA board" but team uses Linear. Template has a "QA Sign-Off" section but team has no QA role. Placeholder text says "TODO: add content here" with no guidance on what content.
### Structural Checklist
- [ ] Metadata header: owner name, version (semver), status (`active`/`deprecated`/`draft`), last-reviewed date
- [ ] Table of Contents macro if template has 4+ sections
- [ ] Change History table at bottom (date, author, change description)
- [ ] Placeholder text uses `{placeholder}` syntax or ac:placeholder macro — visually distinct from real content
### Maintenance Triggers
- Template not reviewed in 90+ days → owner gets Jira ticket auto-created via automation
- 3+ unresolved feedback items → escalate to committee
- Broken macro detected → owner notified same day via Slack/email automation
## Review Cadence
### Quarterly Review (Template Owner)
- Review usage metrics
- Address pending feedback
- Update content for accuracy
- Verify all links and macros work
- Update version number if changed
### Semi-Annual Review (Template Committee)
- Review full template catalog
- Identify gaps (missing templates)
- Identify overlaps (duplicate templates)
- Evaluate template standards compliance
- Plan improvements for next half
### Annual Review (Leadership — 60 min meeting)
**Agenda:**
1. (10 min) Catalog stats: total templates, usage trend YoY, templates added/deprecated
2. (15 min) Top 5 templates by adoption — what makes them work
3. (15 min) Bottom 5 templates — deprecate, rework, or retrain?
4. (10 min) Gaps identified by teams — templates requested but not yet built
5. (10 min) Governance process retro — is the framework itself working? Adjust thresholds, roles, or cadence as needed
**Deliverable:** Updated Template Health page published within 1 week of meeting
## Getting Started
### For New Organizations
1. Start with 5-10 essential templates (meeting notes, decision record, project plan)
2. Assign owners for each template
3. Establish basic quality standards
4. Review after 90 days and expand
5. Formalize governance as template count grows beyond 20

252
project-management/atlassian-templates/references/template-design-patterns.md Normal file
View File

@@ -0,0 +1,252 @@
# Template Design Patterns
## Overview
Well-designed Confluence and Jira templates accelerate team productivity by providing consistent starting points for common documents and workflows. This guide covers design patterns, variable handling, and best practices for creating reusable templates.
## Variable Placeholders
### Confluence Template Variables
**Syntax:** `<at:var at:name="variableName">default value</at:var>`
**Common Variables:**
| Variable | Purpose | Example Default |
|----------|---------|----------------|
| `projectName` | Project identifier | "Project Name" |
| `author` | Document author | "@mention author" |
| `date` | Creation or target date | "YYYY-MM-DD" |
| `status` | Current document status | "Draft" |
| `version` | Document version | "1.0" |
| `owner` | Responsible person | "@mention owner" |
| `reviewers` | Review participants | "@mention reviewers" |
**Best Practices:**
- Use descriptive variable names (camelCase)
- Always provide meaningful default values
- Group related variables together
- Include instruction text that users should replace
- Use Status macro for status variables (visual clarity)
### Jira Template Fields
**Custom Fields for Templates:**
- Text fields for structured input
- Select lists for controlled vocabularies
- Date fields for milestones
- User pickers for assignments
- Labels for categorization
## Conditional Sections
### Pattern: Role-Based Sections
Include or exclude content based on the document's audience:
```
## For Engineering (delete if not applicable)
- Technical requirements
- Architecture decisions
- Performance criteria
## For Design (delete if not applicable)
- User flows
- Wireframes
- Accessibility requirements
## For Business (delete if not applicable)
- ROI analysis
- Market context
- Success metrics
```
### Pattern: Complexity-Based Sections
Scale content depth based on project size:
```
## Required for All Projects
- Problem statement
- Solution overview
- Success metrics
## Required for Medium+ Projects (>2 weeks)
- Detailed requirements
- Technical design
- Test plan
## Required for Large Projects (>1 month)
- Architecture review
- Security review
- Rollback plan
- Communication plan
```
### Pattern: Optional Deep Dives
Use Expand macros for optional detail:
```
[Expand: Detailed Requirements]
Content that power users may need but casual readers can skip
[/Expand]
```
## Reusable Components
### Header Block
Every template should start with a consistent header:
```
| Field | Value |
|-------|-------|
| Author | @mention |
| Status | [Status Macro: Draft] |
| Created | [Date] |
| Last Updated | [Date] |
| Reviewers | @mention |
| Approver | @mention |
```
### Decision Log Component
Reusable across templates that involve decisions:
```
## Decision Log
| # | Decision | Date | Decided By | Rationale |
|---|----------|------|-----------|-----------|
| 1 | [Decision] | [Date] | [Name] | [Why] |
```
### Change History Component
Track document evolution:
```
## Change History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | [Date] | [Name] | Initial version |
```
### Action Items Component
Standard task tracking:
```
## Action Items
- [ ] [Task description] - @assignee - Due: [date]
- [ ] [Task description] - @assignee - Due: [date]
```
## Macro Integration
### Recommended Macros per Template Type
**Meeting Notes Template:**
- Table of Contents (for long meetings)
- Action Items (task list macro)
- Jira Issues (link to discussed tickets)
- Expand (for detailed discussion notes)
**Decision Record Template:**
- Status macro (decision status)
- Page Properties (structured metadata)
- Info/Warning panels (context and caveats)
- Jira Issues (related tickets)
**Project Plan Template:**
- Roadmap Planner (timeline view)
- Jira Issues (JQL for project epics)
- Children Display (sub-pages for phases)
- Chart macro (status distribution)
**Runbook Template:**
- Code Block (commands and scripts)
- Warning panels (danger zones)
- Expand (detailed troubleshooting)
- Anchor links (quick navigation)
## Responsive Layouts
### Two-Column Layout
Use Confluence Section and Column macros:
```
[Section]
[Column: 60%]
Main content, description, details
[/Column]
[Column: 40%]
Sidebar: metadata, quick links, status
[/Column]
[/Section]
```
### Card Layout
For overview pages with multiple items:
```
[Section]
[Column: 33%]
[Panel: Card 1]
Title, summary, link
[/Panel]
[/Column]
[Column: 33%]
[Panel: Card 2]
[/Column]
[Column: 33%]
[Panel: Card 3]
[/Column]
[/Section]
```
## Brand Consistency
### Visual Standards
- Use consistent heading levels (H1 for title, H2 for sections, H3 for subsections)
- Apply Info/Warning/Note panels consistently (same meaning across templates)
- Use Status macro colors consistently (Green=done, Yellow=in progress, Red=blocked)
- Maintain consistent table formatting (header row, alignment)
### Content Standards
- Use the same voice and tone across templates
- Standardize date format (YYYY-MM-DD or your organization's preference)
- Use consistent terminology (define terms in a glossary)
- Include the same footer/metadata block in all templates
## Versioning Strategy
### Template Version Control
- Include version number in template metadata
- Maintain a changelog for template updates
- Communicate template changes to users
- Keep previous versions accessible during transition periods
### Version Numbering
- **Major (2.0):** Structural changes, section additions/removals
- **Minor (1.1):** Content updates, improved instructions
- **Patch (1.0.1):** Typo fixes, formatting corrections
### Migration Path
When updating templates:
1. Create new version alongside old version
2. Announce change with migration guide
3. New documents use new template automatically
4. Existing documents do not need to be migrated (optional)
5. Deprecate old template after 90 days
6. Archive old template (do not delete)
## Template Catalog Organization
### Categorization
Organize templates by:
- **Document type:** Meeting notes, decisions, plans, runbooks
- **Team:** Engineering, product, marketing, HR
- **Lifecycle:** Planning, execution, review, retrospective
- **Frequency:** One-time, recurring, as-needed
### Discovery
- Maintain a "Template Index" page with descriptions and links
- Tag templates with consistent labels
- Include a "When to Use" section in each template
- Provide examples of completed documents using the template

418
project-management/atlassian-templates/scripts/template_scaffolder.py Normal file
View File

@@ -0,0 +1,418 @@
#!/usr/bin/env python3
"""
Template Scaffolder
Generates Confluence page template markup in storage-format XHTML. Supports
built-in template types and custom section definitions with optional macros.
Usage:
python template_scaffolder.py meeting-notes
python template_scaffolder.py decision-log --format json
python template_scaffolder.py custom --sections "Overview,Goals,Action Items" --macros toc,status
python template_scaffolder.py --list
"""
import argparse
import json
import sys
from datetime import datetime
from typing import Any, Dict, List, Optional
# ---------------------------------------------------------------------------
# Macro Generators
# ---------------------------------------------------------------------------
def macro_toc() -> str:
"""Generate table of contents macro."""
return '<ac:structured-macro ac:name="toc"><ac:parameter ac:name="printable">true</ac:parameter><ac:parameter ac:name="style">disc</ac:parameter><ac:parameter ac:name="maxLevel">3</ac:parameter></ac:structured-macro>'
def macro_status(text: str = "IN PROGRESS", color: str = "Yellow") -> str:
"""Generate status macro."""
return f'<ac:structured-macro ac:name="status"><ac:parameter ac:name="colour">{color}</ac:parameter><ac:parameter ac:name="title">{text}</ac:parameter></ac:structured-macro>'
def macro_info_panel(content: str) -> str:
"""Generate info panel macro."""
return f'<ac:structured-macro ac:name="info"><ac:rich-text-body><p>{content}</p></ac:rich-text-body></ac:structured-macro>'
def macro_warning_panel(content: str) -> str:
"""Generate warning panel macro."""
return f'<ac:structured-macro ac:name="warning"><ac:rich-text-body><p>{content}</p></ac:rich-text-body></ac:structured-macro>'
def macro_note_panel(content: str) -> str:
"""Generate note panel macro."""
return f'<ac:structured-macro ac:name="note"><ac:rich-text-body><p>{content}</p></ac:rich-text-body></ac:structured-macro>'
def macro_expand(title: str, content: str) -> str:
"""Generate expand/collapse macro."""
return f'<ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">{title}</ac:parameter><ac:rich-text-body>{content}</ac:rich-text-body></ac:structured-macro>'
def macro_jira_issues(jql: str) -> str:
"""Generate Jira issues macro."""
return f'<ac:structured-macro ac:name="jira"><ac:parameter ac:name="jqlQuery">{jql}</ac:parameter><ac:parameter ac:name="columns">key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution</ac:parameter></ac:structured-macro>'
MACRO_MAP = {
"toc": macro_toc,
"status": macro_status,
"info": macro_info_panel,
"warning": macro_warning_panel,
"note": macro_note_panel,
"expand": macro_expand,
"jira-issues": macro_jira_issues,
}
# ---------------------------------------------------------------------------
# Built-in Templates
# ---------------------------------------------------------------------------
def _section(title: str, content: str) -> str:
"""Generate a section with heading and content."""
return f'<h2>{title}</h2>\n{content}\n'
def _table(headers: List[str], rows: List[List[str]]) -> str:
"""Generate an XHTML table."""
parts = ['<table><colgroup>']
for _ in headers:
parts.append('<col />')
parts.append('</colgroup><thead><tr>')
for h in headers:
parts.append(f'<th><p>{h}</p></th>')
parts.append('</tr></thead><tbody>')
for row in rows:
parts.append('<tr>')
for cell in row:
parts.append(f'<td><p>{cell}</p></td>')
parts.append('</tr>')
parts.append('</tbody></table>')
return ''.join(parts)
def template_meeting_notes() -> Dict[str, Any]:
"""Generate meeting notes template."""
today = datetime.now().strftime("%Y-%m-%d")
body = macro_toc() + '\n'
body += macro_info_panel("Replace placeholder text with your meeting details.") + '\n'
body += _section("Meeting Details", _table(
["Field", "Value"],
[["Date", today], ["Time", ""], ["Location", ""], ["Facilitator", ""], ["Note Taker", ""]],
))
body += _section("Attendees", '<ul><li><p>Name 1</p></li><li><p>Name 2</p></li></ul>')
body += _section("Agenda", '<ol><li><p>Item 1</p></li><li><p>Item 2</p></li><li><p>Item 3</p></li></ol>')
body += _section("Discussion Notes", '<p>Summary of discussion points...</p>')
body += _section("Decisions Made", _table(
["Decision", "Owner", "Date"],
[["", "", today]],
))
body += _section("Action Items", _table(
["Action", "Owner", "Due Date", "Status"],
[["", "", "", macro_status("TODO", "Grey")]],
))
body += _section("Next Meeting", '<p>Date: TBD</p><p>Agenda items for next time:</p><ul><li><p></p></li></ul>')
return {"name": "Meeting Notes", "body": body, "labels": ["meeting-notes", "template"]}
def template_decision_log() -> Dict[str, Any]:
"""Generate decision log template."""
today = datetime.now().strftime("%Y-%m-%d")
body = macro_toc() + '\n'
body += _section("Decision Log", macro_info_panel("Track key decisions, context, and outcomes."))
body += _table(
["ID", "Date", "Decision", "Context", "Alternatives Considered", "Outcome", "Owner", "Status"],
[
["D-001", today, "", "", "", "", "", macro_status("DECIDED", "Green")],
["D-002", "", "", "", "", "", "", macro_status("PENDING", "Yellow")],
],
)
body += '\n'
body += _section("Decision Template", macro_expand("Decision Details Template",
'<h3>Context</h3><p>What is the issue or situation requiring a decision?</p>'
'<h3>Options</h3><ol><li><p>Option A - pros/cons</p></li><li><p>Option B - pros/cons</p></li></ol>'
'<h3>Decision</h3><p>What was decided and why?</p>'
'<h3>Consequences</h3><p>What are the expected outcomes?</p>'
))
return {"name": "Decision Log", "body": body, "labels": ["decision-log", "template"]}
def template_runbook() -> Dict[str, Any]:
"""Generate runbook template."""
body = macro_toc() + '\n'
body += macro_warning_panel("This runbook should be tested and reviewed quarterly.") + '\n'
body += _section("Overview", '<p>Brief description of what this runbook covers.</p>'
+ _table(["Field", "Value"], [
["Service/System", ""], ["Owner", ""], ["Last Tested", ""],
["Severity", ""], ["Estimated Duration", ""],
]))
body += _section("Prerequisites", '<ul><li><p>Access to system X</p></li><li><p>VPN connected</p></li><li><p>Required tools installed</p></li></ul>')
body += _section("Steps", '<ol><li><p><strong>Step 1:</strong> Description</p><ac:structured-macro ac:name="code"><ac:parameter ac:name="language">bash</ac:parameter><ac:plain-text-body><![CDATA[# command here]]></ac:plain-text-body></ac:structured-macro></li>'
'<li><p><strong>Step 2:</strong> Description</p></li>'
'<li><p><strong>Step 3:</strong> Description</p></li></ol>')
body += _section("Verification", '<p>How to verify the issue is resolved:</p><ul><li><p>Check 1</p></li><li><p>Check 2</p></li></ul>')
body += _section("Rollback", macro_note_panel("If the above steps do not resolve the issue, follow these rollback steps.") +
'<ol><li><p>Rollback step 1</p></li><li><p>Rollback step 2</p></li></ol>')
body += _section("Escalation", _table(
["Level", "Contact", "When to Escalate"],
[["L1", "", ""], ["L2", "", ""], ["L3", "", ""]],
))
return {"name": "Runbook", "body": body, "labels": ["runbook", "operations", "template"]}
def template_project_kickoff() -> Dict[str, Any]:
"""Generate project kickoff template."""
today = datetime.now().strftime("%Y-%m-%d")
body = macro_toc() + '\n'
body += _section("Project Overview", _table(
["Field", "Value"],
[["Project Name", ""], ["Start Date", today], ["Target End Date", ""],
["Project Lead", ""], ["Sponsor", ""], ["Status", macro_status("KICKOFF", "Blue")]],
))
body += _section("Vision & Goals", '<h3>Vision</h3><p>What does success look like?</p>'
'<h3>Goals</h3><ol><li><p>Goal 1</p></li><li><p>Goal 2</p></li><li><p>Goal 3</p></li></ol>')
body += _section("Scope", '<h3>In Scope</h3><ul><li><p></p></li></ul><h3>Out of Scope</h3><ul><li><p></p></li></ul>')
body += _section("Stakeholders", _table(
["Name", "Role", "Responsibility", "Communication Preference"],
[["", "", "", ""]],
))
body += _section("Timeline & Milestones", _table(
["Milestone", "Target Date", "Status"],
[["Phase 1", "", macro_status("NOT STARTED", "Grey")],
["Phase 2", "", macro_status("NOT STARTED", "Grey")]],
))
body += _section("Risks", _table(
["Risk", "Likelihood", "Impact", "Mitigation"],
[["", "High/Medium/Low", "High/Medium/Low", ""]],
))
body += _section("Next Steps", '<ul><li><p></p></li></ul>')
return {"name": "Project Kickoff", "body": body, "labels": ["project-kickoff", "template"]}
def template_sprint_retro() -> Dict[str, Any]:
"""Generate sprint retrospective template."""
body = macro_toc() + '\n'
body += _section("Sprint Info", _table(
["Field", "Value"],
[["Sprint", ""], ["Date Range", ""], ["Facilitator", ""],
["Velocity", ""], ["Commitment", ""], ["Completion Rate", ""]],
))
body += _section("What Went Well", '<ul><li><p></p></li></ul>')
body += _section("What Could Be Improved", '<ul><li><p></p></li></ul>')
body += _section("Action Items from Last Retro", _table(
["Action", "Owner", "Status"],
[["", "", macro_status("DONE", "Green")], ["", "", macro_status("IN PROGRESS", "Yellow")]],
))
body += _section("New Action Items", _table(
["Action", "Owner", "Due Date", "Priority"],
[["", "", "", "High/Medium/Low"]],
))
body += _section("Team Health Check", macro_info_panel("Rate each area 1-5 (1=needs work, 5=great)") + _table(
["Area", "Rating", "Trend", "Notes"],
[["Teamwork", "", "", ""], ["Delivery", "", "", ""],
["Fun", "", "", ""], ["Learning", "", "", ""]],
))
return {"name": "Sprint Retrospective", "body": body, "labels": ["sprint-retro", "agile", "template"]}
def template_how_to_guide() -> Dict[str, Any]:
"""Generate how-to guide template."""
body = macro_toc() + '\n'
body += macro_info_panel("This guide explains how to accomplish a specific task.") + '\n'
body += _section("Overview", '<p>Brief description of what this guide covers and who it is for.</p>')
body += _section("Prerequisites", '<ul><li><p>Prerequisite 1</p></li><li><p>Prerequisite 2</p></li></ul>')
body += _section("Step-by-Step Instructions",
'<h3>Step 1: Title</h3><p>Description of what to do.</p>'
'<h3>Step 2: Title</h3><p>Description of what to do.</p>'
'<h3>Step 3: Title</h3><p>Description of what to do.</p>')
body += _section("Troubleshooting", macro_expand("Common Issues",
'<h3>Issue 1</h3><p>Solution...</p>'
'<h3>Issue 2</h3><p>Solution...</p>'))
body += _section("Related Resources", '<ul><li><p>Link 1</p></li><li><p>Link 2</p></li></ul>')
return {"name": "How-To Guide", "body": body, "labels": ["how-to", "guide", "template"]}
TEMPLATE_REGISTRY = {
"meeting-notes": template_meeting_notes,
"decision-log": template_decision_log,
"runbook": template_runbook,
"project-kickoff": template_project_kickoff,
"sprint-retro": template_sprint_retro,
"how-to-guide": template_how_to_guide,
}
# ---------------------------------------------------------------------------
# Custom Template Builder
# ---------------------------------------------------------------------------
def build_custom_template(
sections: List[str],
macros: List[str],
) -> Dict[str, Any]:
"""Build a custom template from sections and macros."""
body = ""
# Add requested macros at the top
if "toc" in macros:
body += macro_toc() + '\n'
if "status" in macros:
body += '<p>Status: ' + macro_status() + '</p>\n'
for section in sections:
section = section.strip()
if not section:
continue
body += _section(section, '<p></p>')
# Add panels if requested
if "info" in macros:
body = macro_info_panel("Add instructions or context here.") + '\n' + body
if "warning" in macros:
body += macro_warning_panel("Add warnings here.") + '\n'
if "note" in macros:
body += macro_note_panel("Add notes here.") + '\n'
return {"name": "Custom Template", "body": body, "labels": ["custom", "template"]}
# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------
def format_text_output(result: Dict[str, Any]) -> str:
"""Format results as readable text report."""
lines = []
lines.append("=" * 60)
lines.append(f"TEMPLATE: {result['name']}")
lines.append("=" * 60)
lines.append("")
lines.append(f"Labels: {', '.join(result.get('labels', []))}")
lines.append("")
lines.append("CONFLUENCE STORAGE FORMAT MARKUP")
lines.append("-" * 30)
lines.append(result["body"])
return "\n".join(lines)
def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
"""Format results as JSON."""
return result
def format_list_output(output_format: str) -> str:
"""Format available templates list."""
if output_format == "json":
templates = {}
for name, func in TEMPLATE_REGISTRY.items():
result = func()
templates[name] = {
"name": result["name"],
"labels": result["labels"],
}
return json.dumps(templates, indent=2)
lines = []
lines.append("=" * 60)
lines.append("AVAILABLE TEMPLATES")
lines.append("=" * 60)
lines.append("")
for name, func in TEMPLATE_REGISTRY.items():
result = func()
lines.append(f" {name}")
lines.append(f" Name: {result['name']}")
lines.append(f" Labels: {', '.join(result['labels'])}")
lines.append("")
lines.append(f"Total templates: {len(TEMPLATE_REGISTRY)}")
lines.append("")
lines.append("Usage:")
lines.append(" python template_scaffolder.py <template-name>")
lines.append(' python template_scaffolder.py custom --sections "Section1,Section2" --macros toc,status')
return "\n".join(lines)
# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------
def main() -> int:
"""Main CLI entry point."""
parser = argparse.ArgumentParser(
description="Generate Confluence page template markup"
)
parser.add_argument(
"template",
nargs="?",
help="Template name or 'custom' for custom template",
)
parser.add_argument(
"--format",
choices=["text", "json"],
default="text",
help="Output format (default: text)",
)
parser.add_argument(
"--list",
action="store_true",
help="List all available template types",
)
parser.add_argument(
"--sections",
help='Comma-separated section names for custom template (e.g., "Overview,Goals,Action Items")',
)
parser.add_argument(
"--macros",
help='Comma-separated macro names to include (e.g., "toc,status,info")',
)
args = parser.parse_args()
try:
if args.list:
print(format_list_output(args.format))
return 0
if not args.template:
parser.error("template name is required unless --list is used")
template_name = args.template.lower()
if template_name == "custom":
if not args.sections:
parser.error("--sections is required for custom templates")
sections = [s.strip() for s in args.sections.split(",")]
macros = [m.strip() for m in args.macros.split(",")] if args.macros else []
result = build_custom_template(sections, macros)
elif template_name in TEMPLATE_REGISTRY:
result = TEMPLATE_REGISTRY[template_name]()
else:
available = ", ".join(sorted(TEMPLATE_REGISTRY.keys()))
print(f"Error: Unknown template '{template_name}'. Available: {available}", file=sys.stderr)
return 1
if args.format == "json":
print(json.dumps(format_json_output(result), indent=2))
else:
print(format_text_output(result))
return 0
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

5
project-management/confluence-expert/SKILL.md
View File

@@ -368,3 +368,8 @@ const example = "code here";
- Duplicate content - Duplicate content
- Broken links - Broken links
- Empty spaces - Empty spaces
## Related Skills
- **Jira Expert** (`project-management/jira-expert/`) — Jira issue macros and linking complement Confluence docs
- **Atlassian Templates** (`project-management/atlassian-templates/`) — Template patterns for Confluence content creation

144
project-management/confluence-expert/references/macro-cheat-sheet.md Normal file
View File

@@ -0,0 +1,144 @@
# Confluence Macro Cheat Sheet
## Overview
Quick reference for the most commonly used Confluence macros. Each entry includes the macro name, storage format syntax, primary use case, and practical tips.
## Navigation & Structure Macros
### Table of Contents
- **Purpose:** Auto-generate a linked table of contents from page headings
- **Syntax:** `<ac:structured-macro ac:name="toc" />`
- **Parameters:** `maxLevel` (1-6), `minLevel` (1-6), `style` (disc, circle, square, none), `type` (list, flat)
- **Use case:** Long documentation pages, meeting notes, specifications
- **Tip:** Set `maxLevel="3"` to avoid overly deep TOC entries
### Children Display
- **Purpose:** List child pages of the current page
- **Syntax:** `<ac:structured-macro ac:name="children" />`
- **Parameters:** `depth` (1-999), `sort` (title, creation, modified), `style` (h2-h6), `all` (true/false)
- **Use case:** Parent hub pages, project homepages, documentation indexes
- **Tip:** Use `depth="1"` for clean navigation, `all="true"` for deep hierarchies
### Include Page
- **Purpose:** Embed content from another page inline
- **Syntax:** `<ac:structured-macro ac:name="include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Page Name" /></ac:link></ac:parameter></ac:structured-macro>`
- **Use case:** Reusable content blocks (headers, footers, disclaimers)
- **Tip:** Changes to the source page are reflected everywhere it is included
### Page Properties
- **Purpose:** Define structured metadata on a page (key-value pairs)
- **Syntax:** `<ac:structured-macro ac:name="details">` with table inside
- **Use case:** Project metadata, status tracking, structured page data
- **Tip:** Combine with Page Properties Report macro to create dashboards
### Page Properties Report
- **Purpose:** Display a table of Page Properties from child pages
- **Syntax:** `<ac:structured-macro ac:name="detailssummary" />`
- **Parameters:** `cql` (CQL filter), `labels` (filter by label)
- **Use case:** Project dashboards, status rollups, portfolio views
- **Tip:** Use labels to scope the report to relevant pages only
## Visual & Formatting Macros
### Info Panel
- **Purpose:** Blue information callout box
- **Syntax:** `<ac:structured-macro ac:name="info"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
- **Use case:** Helpful notes, additional context, best practices
### Warning Panel
- **Purpose:** Yellow warning callout box
- **Syntax:** `<ac:structured-macro ac:name="warning"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
- **Use case:** Important caveats, deprecation notices, breaking changes
### Note Panel
- **Purpose:** Yellow note callout box
- **Syntax:** `<ac:structured-macro ac:name="note"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
- **Use case:** Reminders, action items, things to watch
### Tip Panel
- **Purpose:** Green tip callout box
- **Syntax:** `<ac:structured-macro ac:name="tip"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
- **Use case:** Pro tips, shortcuts, recommended approaches
### Expand
- **Purpose:** Collapsible content section (click to expand)
- **Syntax:** `<ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">Click to expand</ac:parameter><ac:rich-text-body>Hidden content</ac:rich-text-body></ac:structured-macro>`
- **Use case:** Long sections, FAQs, detailed explanations, optional reading
- **Tip:** Use for content that not all readers need
### Status
- **Purpose:** Colored status lozenge (inline label)
- **Syntax:** `<ac:structured-macro ac:name="status"><ac:parameter ac:name="colour">Green</ac:parameter><ac:parameter ac:name="title">DONE</ac:parameter></ac:structured-macro>`
- **Colors:** Grey, Red, Yellow, Green, Blue
- **Use case:** Task status, review state, approval status
- **Tip:** Standardize status values across your team (e.g., TODO, IN PROGRESS, DONE)
## Integration Macros
### Jira Issues
- **Purpose:** Display Jira issues or JQL query results
- **Syntax:** `<ac:structured-macro ac:name="jira"><ac:parameter ac:name="jqlQuery">project = PROJ AND status = Open</ac:parameter></ac:structured-macro>`
- **Parameters:** `jqlQuery`, `columns` (key, summary, status, assignee, etc.), `count` (true/false), `serverId`
- **Use case:** Sprint boards in documentation, requirement traceability, release notes
- **Tip:** Use `columns` parameter to show only relevant fields
### Roadmap Planner
- **Purpose:** Visual timeline/Gantt view of items
- **Syntax:** Available via macro browser (Roadmap Planner)
- **Use case:** Project timelines, release planning, milestone tracking
- **Tip:** Link roadmap items to Jira epics for automatic status updates
### Chart Macro
- **Purpose:** Create charts from table data on the page
- **Syntax:** `<ac:structured-macro ac:name="chart"><ac:parameter ac:name="type">pie</ac:parameter><ac:rich-text-body>Table data</ac:rich-text-body></ac:structured-macro>`
- **Types:** pie, bar, line, area, scatter, timeSeries
- **Use case:** Status distribution, metrics dashboards, trend visualization
- **Tip:** Place a Confluence table inside the macro body as data source
## Content Reuse Macros
### Excerpt
- **Purpose:** Mark a section of content for reuse via Excerpt Include
- **Syntax:** `<ac:structured-macro ac:name="excerpt"><ac:rich-text-body>Reusable content</ac:rich-text-body></ac:structured-macro>`
- **Use case:** Define canonical content blocks (product descriptions, team info)
### Excerpt Include
- **Purpose:** Display an Excerpt from another page
- **Syntax:** `<ac:structured-macro ac:name="excerpt-include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Source Page" /></ac:link></ac:parameter></ac:structured-macro>`
- **Use case:** Embed product descriptions, standard disclaimers, shared definitions
## Advanced Macros
### Code Block
- **Purpose:** Display formatted code with syntax highlighting
- **Syntax:** `<ac:structured-macro ac:name="code"><ac:parameter ac:name="language">python</ac:parameter><ac:plain-text-body>code here</ac:plain-text-body></ac:structured-macro>`
- **Languages:** java, python, javascript, sql, bash, xml, json, and many more
- **Use case:** API documentation, configuration examples, code snippets
### Anchor
- **Purpose:** Create a named anchor point for deep linking
- **Syntax:** `<ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">anchor-name</ac:parameter></ac:structured-macro>`
- **Use case:** Link directly to specific sections within long pages
- **Tip:** Use with TOC macro for custom navigation
### Recently Updated
- **Purpose:** Show recently modified pages in a space
- **Syntax:** `<ac:structured-macro ac:name="recently-updated" />`
- **Parameters:** `spaces`, `labels`, `types`, `max`
- **Use case:** Team dashboards, space homepages, activity feeds
## Macro Selection Guide
| Need | Recommended Macro |
|------|------------------|
| Page navigation | Table of Contents |
| List child pages | Children Display |
| Reuse content | Include Page or Excerpt Include |
| Status tracking | Status + Page Properties |
| Project dashboard | Page Properties Report |
| Hide optional content | Expand |
| Show Jira data | Jira Issues |
| Visualize data | Chart |
| Code documentation | Code Block |
| Important callouts | Info/Warning/Note/Tip panels |

246
project-management/confluence-expert/references/space-architecture-patterns.md Normal file
View File

@@ -0,0 +1,246 @@
# Confluence Space Architecture Patterns
## Overview
Well-organized Confluence spaces dramatically improve information discoverability and team productivity. This guide covers proven space organization patterns, page hierarchy best practices, and governance strategies.
## Space Organization Patterns
### Pattern 1: By Team
Each team or department gets its own space.
**Structure:**
```
Engineering Space (ENG)
Product Space (PROD)
Marketing Space (MKT)
Design Space (DES)
Support Space (SUP)
```
**Pros:**
- Clear ownership and permissions
- Teams control their own content
- Natural permission boundaries
- Easy to find team-specific content
**Cons:**
- Cross-team content duplication
- Silos between departments
- Hard to find project-spanning information
- Inconsistent practices across spaces
**Best for:** Organizations with stable teams and clear departmental boundaries
### Pattern 2: By Project
Each major project or product gets its own space.
**Structure:**
```
Project Alpha Space (ALPHA)
Project Beta Space (BETA)
Platform Infrastructure Space (PLAT)
Internal Tools Space (TOOLS)
```
**Pros:**
- All project context in one place
- Easy onboarding for project members
- Clean archival when project completes
- Natural lifecycle management
**Cons:**
- Team knowledge scattered across spaces
- Permission management per project
- Space proliferation over time
- Ongoing vs project work separation unclear
**Best for:** Project-based organizations, agencies, consulting firms
### Pattern 3: By Domain (Hybrid)
Combine functional spaces with cross-cutting project spaces.
**Structure:**
```
Company Wiki (WIKI) - Shared knowledge
Engineering Standards (ENG) - Team practices
Product Specs (PROD) - Requirements and roadmap
Project Alpha (ALPHA) - Cross-team project
Project Beta (BETA) - Cross-team project
Archive (ARCH) - Completed projects
```
**Pros:**
- Balances team and project needs
- Shared knowledge has a home
- Clear archival path
- Scales with organization growth
**Cons:**
- More complex to set up initially
- Requires governance to maintain
- Some ambiguity about where content belongs
**Best for:** Growing organizations, 50-500 people, multiple concurrent projects
## Page Hierarchy Best Practices
### Recommended Depth
- **Maximum 4 levels deep** - Deeper hierarchies become hard to navigate
- **3 levels ideal** for most content types
- Use flat structures with labels for categorization beyond 4 levels
### Standard Page Hierarchy
```
Space Home (overview, quick links, recent updates)
├── Getting Started
│ ├── Onboarding Guide
│ ├── Tool Setup
│ └── Key Contacts
├── Projects
│ ├── Project Alpha
│ │ ├── Requirements
│ │ ├── Design
│ │ └── Meeting Notes
│ └── Project Beta
├── Processes
│ ├── Development Workflow
│ ├── Release Process
│ └── On-Call Runbook
├── References
│ ├── Architecture Decisions
│ ├── API Documentation
│ └── Glossary
└── Archive
├── 2025 Projects
└── Deprecated Processes
```
### Page Naming Conventions
- Use clear, descriptive titles (not abbreviations)
- Include date for time-sensitive content: "2025-Q1 Planning"
- Prefix meeting notes with date: "2025-03-15 Sprint Review"
- Use consistent casing (Title Case or Sentence case, not both)
- Avoid special characters that break URLs
### Space Homepage Design
Every space homepage should include:
1. **Space purpose** - One paragraph describing what this space is for
2. **Quick links** - 5-7 most accessed pages
3. **Recent updates** - Recently Updated macro filtered to this space
4. **Getting started** - Link to onboarding content for new members
5. **Contact info** - Space owner, key contributors
## Labeling Taxonomy
### Label Categories
- **Content type:** `meeting-notes`, `decision`, `specification`, `runbook`, `retrospective`
- **Status:** `draft`, `in-review`, `approved`, `deprecated`, `archived`
- **Team:** `team-engineering`, `team-product`, `team-design`
- **Project:** `project-alpha`, `project-beta`
- **Priority:** `high-priority`, `p1`, `critical`
### Labeling Best Practices
- Use lowercase, hyphenated labels (no spaces or camelCase)
- Define a standard label vocabulary and document it
- Use labels for cross-space categorization
- Combine labels with CQL for powerful search and reporting
- Audit labels quarterly to remove unused or inconsistent labels
- Limit to 3-5 labels per page (over-labeling reduces value)
### CQL Examples for Label-Based Queries
```
# All meeting notes in a space
type = page AND space = "ENG" AND label = "meeting-notes"
# All approved specifications
type = page AND label = "specification" AND label = "approved"
# Recent decisions across all spaces
type = page AND label = "decision" AND lastModified > now("-30d")
```
## Cross-Space Linking
### When to Link vs Duplicate
- **Link** when content has a single source of truth
- **Duplicate** (Include Page macro) when content must appear in multiple contexts
- **Excerpt Include** when only a portion of a page is needed elsewhere
### Linking Best Practices
- Use full page titles in links for clarity
- Add context around links ("See the [Architecture Decision Record] for rationale")
- Avoid orphan pages - every page should be reachable from space navigation
- Use the Recently Updated macro on hub pages for activity visibility
- Create "Related Pages" sections at the bottom of content pages
## Archive Strategy
### When to Archive
- Project completed more than 90 days ago
- Process or document officially deprecated
- Content not updated in 12+ months
- Replaced by newer content
### Archive Process
1. Add `archived` label to the page
2. Move to Archive section within the space (or dedicated Archive space)
3. Add a note at the top: "This page is archived as of [date]. See [replacement] for current information."
4. Update any incoming links to point to current content
5. Do NOT delete - archived content has historical value
### Archive Space Pattern
- Create a dedicated `Archive` space for completed projects
- Move entire project page trees to Archive space on completion
- Set Archive space to read-only permissions
- Review Archive space annually for content that can be deleted
## Permission Inheritance Patterns
### Pattern 1: Open by Default
- All spaces readable by all employees
- Edit restricted to space members
- Admin restricted to space owners
- **Best for:** Transparency-focused organizations
### Pattern 2: Restricted by Default
- Spaces accessible only to specific groups
- Request access via space admin
- **Best for:** Regulated industries, confidential projects
### Pattern 3: Tiered Access
- Public tier: Company wiki, shared processes
- Team tier: Team-specific spaces with team access
- Restricted tier: HR, finance, legal with limited access
- **Best for:** Most organizations (balanced approach)
### Permission Tips
- Use Confluence groups, not individual users, for permissions
- Align groups with LDAP/SSO groups where possible
- Audit permissions quarterly
- Document permission model on the space homepage
- Use page-level restrictions sparingly (breaks inheritance, hard to audit)
## Scaling Considerations
### < 50 People
- 3-5 spaces total
- Simple by-team pattern
- Light governance
### 50-200 People
- 10-20 spaces
- Hybrid pattern (team + project)
- Formal labeling taxonomy
- Quarterly content reviews
### 200+ People
- 20-50+ spaces
- Full domain pattern with governance
- Space owners and content stewards
- Automated archival policies
- Regular information architecture reviews

457
project-management/confluence-expert/scripts/content_audit_analyzer.py Normal file
View File

@@ -0,0 +1,457 @@
#!/usr/bin/env python3
"""
Content Audit Analyzer
Analyzes Confluence page inventory for content health. Identifies stale pages,
low-engagement content, orphaned pages, oversized documents, and produces a
health score with actionable recommendations.
Usage:
python content_audit_analyzer.py pages.json
python content_audit_analyzer.py pages.json --format json
"""
import argparse
import json
import sys
from datetime import datetime, timedelta
from typing import Any, Dict, List, Optional, Tuple
# ---------------------------------------------------------------------------
# Audit Configuration
# ---------------------------------------------------------------------------
STALE_THRESHOLD_DAYS = 90
OUTDATED_THRESHOLD_DAYS = 180
LOW_VIEW_THRESHOLD = 5
OVERSIZED_WORD_THRESHOLD = 5000
IDEAL_WORD_RANGE = (200, 3000)
HEALTH_WEIGHTS = {
"freshness": 0.30,
"engagement": 0.25,
"organization": 0.20,
"size_balance": 0.15,
"completeness": 0.10,
}
# ---------------------------------------------------------------------------
# Audit Checks
# ---------------------------------------------------------------------------
def check_stale_pages(
pages: List[Dict[str, Any]],
reference_date: datetime,
) -> Dict[str, Any]:
"""Identify pages not updated within the stale threshold."""
stale = []
outdated = []
for page in pages:
last_modified = _parse_date(page.get("last_modified", ""))
if not last_modified:
continue
days_since_update = (reference_date - last_modified).days
if days_since_update > OUTDATED_THRESHOLD_DAYS:
outdated.append({
"title": page.get("title", "Untitled"),
"days_since_update": days_since_update,
"last_modified": page.get("last_modified", ""),
"author": page.get("author", "unknown"),
})
elif days_since_update > STALE_THRESHOLD_DAYS:
stale.append({
"title": page.get("title", "Untitled"),
"days_since_update": days_since_update,
"last_modified": page.get("last_modified", ""),
"author": page.get("author", "unknown"),
})
total = len(pages)
stale_count = len(stale) + len(outdated)
fresh_ratio = 1 - (stale_count / total) if total > 0 else 1
score = max(0, fresh_ratio * 100)
return {
"score": score,
"stale_pages": stale,
"outdated_pages": outdated,
"stale_count": len(stale),
"outdated_count": len(outdated),
"fresh_count": total - stale_count,
}
def check_engagement(pages: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Identify low-engagement pages based on view counts."""
low_engagement = []
view_counts = []
for page in pages:
views = page.get("view_count", 0)
view_counts.append(views)
if views < LOW_VIEW_THRESHOLD:
low_engagement.append({
"title": page.get("title", "Untitled"),
"view_count": views,
"author": page.get("author", "unknown"),
})
total = len(pages)
avg_views = sum(view_counts) / total if total > 0 else 0
engaged_ratio = 1 - (len(low_engagement) / total) if total > 0 else 1
score = max(0, engaged_ratio * 100)
return {
"score": score,
"low_engagement_pages": low_engagement,
"low_engagement_count": len(low_engagement),
"average_views": round(avg_views, 1),
"max_views": max(view_counts) if view_counts else 0,
"min_views": min(view_counts) if view_counts else 0,
}
def check_organization(pages: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Identify orphaned pages with no labels."""
orphaned = []
for page in pages:
labels = page.get("labels", [])
if not labels:
orphaned.append({
"title": page.get("title", "Untitled"),
"author": page.get("author", "unknown"),
})
total = len(pages)
labeled_ratio = 1 - (len(orphaned) / total) if total > 0 else 1
score = max(0, labeled_ratio * 100)
# Collect label distribution
label_counts = {}
for page in pages:
for label in page.get("labels", []):
label_counts[label] = label_counts.get(label, 0) + 1
return {
"score": score,
"orphaned_pages": orphaned,
"orphaned_count": len(orphaned),
"labeled_count": total - len(orphaned),
"label_distribution": dict(sorted(label_counts.items(), key=lambda x: -x[1])[:20]),
}
def check_size_balance(pages: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Check for oversized or undersized pages."""
oversized = []
undersized = []
word_counts = []
for page in pages:
word_count = page.get("word_count", 0)
word_counts.append(word_count)
if word_count > OVERSIZED_WORD_THRESHOLD:
oversized.append({
"title": page.get("title", "Untitled"),
"word_count": word_count,
"recommendation": "Split into multiple focused pages",
})
elif word_count < 50 and word_count > 0:
undersized.append({
"title": page.get("title", "Untitled"),
"word_count": word_count,
"recommendation": "Expand content or merge with related page",
})
total = len(pages)
well_sized = total - len(oversized) - len(undersized)
balance_ratio = well_sized / total if total > 0 else 1
score = max(0, balance_ratio * 100)
avg_words = sum(word_counts) / total if total > 0 else 0
return {
"score": score,
"oversized_pages": oversized,
"undersized_pages": undersized,
"oversized_count": len(oversized),
"undersized_count": len(undersized),
"average_word_count": round(avg_words),
}
def check_completeness(pages: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Check pages for required metadata completeness."""
incomplete = []
required_fields = ["title", "last_modified", "author"]
for page in pages:
missing = [f for f in required_fields if not page.get(f)]
if missing:
incomplete.append({
"title": page.get("title", "Untitled"),
"missing_fields": missing,
})
total = len(pages)
complete_ratio = 1 - (len(incomplete) / total) if total > 0 else 1
score = max(0, complete_ratio * 100)
return {
"score": score,
"incomplete_pages": incomplete,
"incomplete_count": len(incomplete),
"complete_count": total - len(incomplete),
}
# ---------------------------------------------------------------------------
# Main Analysis
# ---------------------------------------------------------------------------
def analyze_content_health(data: Dict[str, Any]) -> Dict[str, Any]:
"""Run full content audit analysis."""
pages = data.get("pages", [])
if not pages:
return {
"health_score": 0,
"grade": "invalid",
"error": "No pages found in input data",
"dimensions": {},
"action_items": [],
}
reference_date = datetime.now()
# Run all checks
dimensions = {
"freshness": check_stale_pages(pages, reference_date),
"engagement": check_engagement(pages),
"organization": check_organization(pages),
"size_balance": check_size_balance(pages),
"completeness": check_completeness(pages),
}
# Calculate weighted health score
weighted_scores = []
for dim_name, dim_result in dimensions.items():
weight = HEALTH_WEIGHTS.get(dim_name, 0.1)
weighted_scores.append(dim_result["score"] * weight)
health_score = sum(weighted_scores)
if health_score >= 85:
grade = "excellent"
elif health_score >= 70:
grade = "good"
elif health_score >= 55:
grade = "fair"
else:
grade = "poor"
# Generate action items
action_items = _generate_action_items(dimensions)
return {
"health_score": round(health_score, 1),
"grade": grade,
"total_pages": len(pages),
"dimensions": dimensions,
"action_items": action_items,
}
def _generate_action_items(dimensions: Dict[str, Any]) -> List[Dict[str, str]]:
"""Generate prioritized action items from audit findings."""
items = []
# Freshness actions
freshness = dimensions.get("freshness", {})
if freshness.get("outdated_count", 0) > 0:
items.append({
"priority": "high",
"action": f"Review and update or archive {freshness['outdated_count']} outdated pages (>180 days old)",
"category": "freshness",
})
if freshness.get("stale_count", 0) > 0:
items.append({
"priority": "medium",
"action": f"Review {freshness['stale_count']} stale pages (90-180 days old) for relevance",
"category": "freshness",
})
# Engagement actions
engagement = dimensions.get("engagement", {})
if engagement.get("low_engagement_count", 0) > 0:
items.append({
"priority": "medium",
"action": f"Investigate {engagement['low_engagement_count']} low-engagement pages - consider improving discoverability or archiving",
"category": "engagement",
})
# Organization actions
organization = dimensions.get("organization", {})
if organization.get("orphaned_count", 0) > 0:
items.append({
"priority": "medium",
"action": f"Add labels to {organization['orphaned_count']} orphaned pages for better categorization",
"category": "organization",
})
# Size actions
size = dimensions.get("size_balance", {})
if size.get("oversized_count", 0) > 0:
items.append({
"priority": "low",
"action": f"Split {size['oversized_count']} oversized pages (>5000 words) into focused sub-pages",
"category": "size",
})
# Completeness actions
completeness = dimensions.get("completeness", {})
if completeness.get("incomplete_count", 0) > 0:
items.append({
"priority": "low",
"action": f"Fill in missing metadata for {completeness['incomplete_count']} incomplete pages",
"category": "completeness",
})
return items
def _parse_date(date_str: str) -> Optional[datetime]:
"""Parse date string in common formats."""
formats = [
"%Y-%m-%d",
"%Y-%m-%dT%H:%M:%S",
"%Y-%m-%dT%H:%M:%SZ",
"%Y-%m-%dT%H:%M:%S.%f",
"%Y-%m-%dT%H:%M:%S.%fZ",
"%d/%m/%Y",
"%m/%d/%Y",
]
for fmt in formats:
try:
return datetime.strptime(date_str, fmt)
except ValueError:
continue
return None
# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------
def format_text_output(result: Dict[str, Any]) -> str:
"""Format results as readable text report."""
lines = []
lines.append("=" * 60)
lines.append("CONTENT AUDIT REPORT")
lines.append("=" * 60)
lines.append("")
if "error" in result:
lines.append(f"ERROR: {result['error']}")
return "\n".join(lines)
lines.append("HEALTH SUMMARY")
lines.append("-" * 30)
lines.append(f"Health Score: {result['health_score']}/100")
lines.append(f"Grade: {result['grade'].title()}")
lines.append(f"Total Pages Analyzed: {result['total_pages']}")
lines.append("")
# Dimension scores
lines.append("DIMENSION SCORES")
lines.append("-" * 30)
for dim_name, dim_data in result.get("dimensions", {}).items():
weight = HEALTH_WEIGHTS.get(dim_name, 0)
lines.append(f"{dim_name.replace('_', ' ').title()} (Weight: {weight:.0%})")
lines.append(f" Score: {dim_data['score']:.1f}/100")
if dim_name == "freshness":
lines.append(f" Stale: {dim_data.get('stale_count', 0)}, Outdated: {dim_data.get('outdated_count', 0)}, Fresh: {dim_data.get('fresh_count', 0)}")
elif dim_name == "engagement":
lines.append(f" Low Engagement: {dim_data.get('low_engagement_count', 0)}, Avg Views: {dim_data.get('average_views', 0)}")
elif dim_name == "organization":
lines.append(f" Orphaned (no labels): {dim_data.get('orphaned_count', 0)}, Labeled: {dim_data.get('labeled_count', 0)}")
elif dim_name == "size_balance":
lines.append(f" Oversized: {dim_data.get('oversized_count', 0)}, Undersized: {dim_data.get('undersized_count', 0)}, Avg Words: {dim_data.get('average_word_count', 0)}")
elif dim_name == "completeness":
lines.append(f" Incomplete: {dim_data.get('incomplete_count', 0)}, Complete: {dim_data.get('complete_count', 0)}")
lines.append("")
# Action items
action_items = result.get("action_items", [])
if action_items:
lines.append("ACTION ITEMS")
lines.append("-" * 30)
for i, item in enumerate(action_items, 1):
priority = item["priority"].upper()
lines.append(f"{i}. [{priority}] {item['action']}")
lines.append("")
return "\n".join(lines)
def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
"""Format results as JSON."""
return result
# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------
def main() -> int:
"""Main CLI entry point."""
parser = argparse.ArgumentParser(
description="Analyze Confluence page inventory for content health"
)
parser.add_argument(
"pages_file",
help="JSON file with page list (title, last_modified, view_count, author, labels, word_count)",
)
parser.add_argument(
"--format",
choices=["text", "json"],
default="text",
help="Output format (default: text)",
)
args = parser.parse_args()
try:
with open(args.pages_file, "r") as f:
data = json.load(f)
result = analyze_content_health(data)
if args.format == "json":
print(json.dumps(format_json_output(result), indent=2))
else:
print(format_text_output(result))
return 0
except FileNotFoundError:
print(f"Error: File '{args.pages_file}' not found", file=sys.stderr)
return 1
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON in '{args.pages_file}': {e}", file=sys.stderr)
return 1
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

517
project-management/confluence-expert/scripts/space_structure_generator.py Normal file
View File

@@ -0,0 +1,517 @@
#!/usr/bin/env python3
"""
Space Structure Generator
Generates recommended Confluence space hierarchy from team or project
descriptions. Produces page tree structures, labels, and permission
suggestions based on team type and size.
Usage:
python space_structure_generator.py team_info.json
python space_structure_generator.py team_info.json --format json
"""
import argparse
import json
import sys
from typing import Any, Dict, List, Optional
# ---------------------------------------------------------------------------
# Space Templates
# ---------------------------------------------------------------------------
BASE_SECTIONS = [
{
"title": "Home",
"description": "Space landing page with quick links and team overview",
"labels": ["home", "landing"],
"children": [],
},
{
"title": "Getting Started",
"description": "Onboarding guide for new team members",
"labels": ["onboarding", "getting-started"],
"children": [
{"title": "Team Charter", "labels": ["charter"]},
{"title": "Tools & Access", "labels": ["tools", "access"]},
{"title": "Communication Guidelines", "labels": ["communication"]},
{"title": "Key Contacts", "labels": ["contacts"]},
],
},
{
"title": "Meeting Notes",
"description": "Recurring and ad-hoc meeting documentation",
"labels": ["meetings"],
"children": [
{"title": "Weekly Standups", "labels": ["standup", "recurring"]},
{"title": "Team Syncs", "labels": ["sync", "recurring"]},
{"title": "Ad-hoc Meetings", "labels": ["ad-hoc"]},
],
},
{
"title": "Templates",
"description": "Reusable page templates for the team",
"labels": ["templates"],
"children": [],
},
{
"title": "Archive",
"description": "Archived and deprecated content",
"labels": ["archive"],
"children": [],
},
]
TEAM_TYPE_SECTIONS = {
"engineering": [
{
"title": "Architecture",
"description": "System architecture, design decisions, and technical standards",
"labels": ["architecture", "technical"],
"children": [
{"title": "Architecture Decision Records", "labels": ["adr", "decisions"]},
{"title": "System Design Documents", "labels": ["design", "system"]},
{"title": "API Documentation", "labels": ["api", "reference"]},
{"title": "Tech Stack", "labels": ["tech-stack"]},
],
},
{
"title": "Development",
"description": "Development workflows, coding standards, and CI/CD",
"labels": ["development"],
"children": [
{"title": "Coding Standards", "labels": ["standards", "code"]},
{"title": "Git Workflow", "labels": ["git", "workflow"]},
{"title": "CI/CD Pipeline", "labels": ["ci-cd", "devops"]},
{"title": "Environment Setup", "labels": ["environment", "setup"]},
],
},
{
"title": "Runbooks",
"description": "Operational runbooks and incident response",
"labels": ["runbooks", "operations"],
"children": [
{"title": "Incident Response", "labels": ["incident", "response"]},
{"title": "Deployment Procedures", "labels": ["deployment"]},
{"title": "Troubleshooting Guides", "labels": ["troubleshooting"]},
],
},
],
"product": [
{
"title": "Strategy",
"description": "Product vision, roadmap, and strategic planning",
"labels": ["strategy", "product"],
"children": [
{"title": "Product Vision", "labels": ["vision"]},
{"title": "Roadmap", "labels": ["roadmap"]},
{"title": "OKRs & Goals", "labels": ["okr", "goals"]},
{"title": "Competitive Analysis", "labels": ["competitive", "analysis"]},
],
},
{
"title": "Research",
"description": "User research, personas, and market analysis",
"labels": ["research"],
"children": [
{"title": "User Personas", "labels": ["personas"]},
{"title": "User Interview Notes", "labels": ["interviews", "research"]},
{"title": "Survey Results", "labels": ["surveys"]},
{"title": "Usability Testing", "labels": ["usability", "testing"]},
],
},
{
"title": "Requirements",
"description": "Product requirements and feature specifications",
"labels": ["requirements", "specs"],
"children": [
{"title": "Feature Specifications", "labels": ["features", "specs"]},
{"title": "User Stories", "labels": ["user-stories"]},
{"title": "Acceptance Criteria", "labels": ["acceptance-criteria"]},
],
},
],
"marketing": [
{
"title": "Strategy",
"description": "Marketing strategy, brand guidelines, and campaign plans",
"labels": ["strategy", "marketing"],
"children": [
{"title": "Brand Guidelines", "labels": ["brand", "guidelines"]},
{"title": "Marketing Plan", "labels": ["plan"]},
{"title": "Target Audiences", "labels": ["audience", "targeting"]},
{"title": "Channel Strategy", "labels": ["channels"]},
],
},
{
"title": "Campaigns",
"description": "Active and past campaign documentation",
"labels": ["campaigns"],
"children": [
{"title": "Active Campaigns", "labels": ["active"]},
{"title": "Campaign Results", "labels": ["results", "analytics"]},
{"title": "Campaign Templates", "labels": ["templates"]},
],
},
{
"title": "Content",
"description": "Content calendar, assets, and style guides",
"labels": ["content"],
"children": [
{"title": "Content Calendar", "labels": ["calendar"]},
{"title": "Content Assets", "labels": ["assets"]},
{"title": "Style Guide", "labels": ["style-guide"]},
],
},
],
"project": [
{
"title": "Project Overview",
"description": "Project charter, scope, and stakeholders",
"labels": ["project", "overview"],
"children": [
{"title": "Project Charter", "labels": ["charter"]},
{"title": "Scope & Deliverables", "labels": ["scope", "deliverables"]},
{"title": "Stakeholder Map", "labels": ["stakeholders"]},
{"title": "Timeline & Milestones", "labels": ["timeline", "milestones"]},
],
},
{
"title": "Status & Reporting",
"description": "Project status updates and reports",
"labels": ["status", "reporting"],
"children": [
{"title": "Weekly Status Reports", "labels": ["status", "weekly"]},
{"title": "Risk Register", "labels": ["risks"]},
{"title": "Decision Log", "labels": ["decisions"]},
],
},
{
"title": "Resources",
"description": "Project resources, documentation, and references",
"labels": ["resources"],
"children": [
{"title": "Technical Documentation", "labels": ["technical", "docs"]},
{"title": "Vendor Information", "labels": ["vendor"]},
{"title": "Budget & Financials", "labels": ["budget"]},
],
},
],
}
# Permission suggestions by team type
PERMISSION_TEMPLATES = {
"engineering": {
"admins": ["team-leads", "engineering-managers"],
"contributors": ["developers", "qa-engineers"],
"viewers": ["product-team", "stakeholders"],
"restrictions": [
"Restrict 'Runbooks' section to engineering team only",
"Allow product team view-only access to Architecture",
],
},
"product": {
"admins": ["product-managers", "product-leads"],
"contributors": ["product-designers", "product-analysts"],
"viewers": ["engineering-team", "marketing-team", "stakeholders"],
"restrictions": [
"Restrict 'Research' raw data to product team only",
"Share 'Strategy' with leadership and stakeholders",
],
},
"marketing": {
"admins": ["marketing-managers", "marketing-leads"],
"contributors": ["content-creators", "designers"],
"viewers": ["sales-team", "product-team"],
"restrictions": [
"Restrict campaign budgets to marketing leadership",
"Share brand guidelines broadly",
],
},
"project": {
"admins": ["project-managers"],
"contributors": ["project-team-members"],
"viewers": ["stakeholders", "sponsors"],
"restrictions": [
"Restrict 'Budget & Financials' to project managers and sponsors",
"Share status reports with all stakeholders",
],
},
}
# ---------------------------------------------------------------------------
# Structure Generator
# ---------------------------------------------------------------------------
def generate_space_structure(team_info: Dict[str, Any]) -> Dict[str, Any]:
"""Generate Confluence space structure from team information."""
team_name = team_info.get("name", "Team")
team_type = team_info.get("type", "project").lower()
team_size = team_info.get("size", 5)
projects = team_info.get("projects", [])
if team_type not in TEAM_TYPE_SECTIONS:
team_type = "project"
# Build page tree
page_tree = []
# Add base sections
for section in BASE_SECTIONS:
page_tree.append(_deep_copy_section(section))
# Add team-type-specific sections
type_sections = TEAM_TYPE_SECTIONS.get(team_type, [])
for section in type_sections:
page_tree.append(_deep_copy_section(section))
# Add project-specific pages if projects are listed
if projects:
project_section = {
"title": "Projects",
"description": "Individual project documentation",
"labels": ["projects"],
"children": [],
}
for project in projects:
project_name = project if isinstance(project, str) else project.get("name", "Project")
project_section["children"].append({
"title": project_name,
"labels": ["project", _slugify(project_name)],
"children": [
{"title": f"{project_name} - Overview", "labels": ["overview"]},
{"title": f"{project_name} - Requirements", "labels": ["requirements"]},
{"title": f"{project_name} - Status", "labels": ["status"]},
],
})
page_tree.append(project_section)
# Get permissions
permissions = PERMISSION_TEMPLATES.get(team_type, PERMISSION_TEMPLATES["project"])
# Generate label taxonomy
all_labels = set()
_collect_labels(page_tree, all_labels)
# Build recommendations
recommendations = _generate_recommendations(team_name, team_type, team_size, projects)
return {
"space_key": _generate_space_key(team_name),
"space_name": f"{team_name} Space",
"team_type": team_type,
"team_size": team_size,
"page_tree": page_tree,
"total_pages": _count_pages(page_tree),
"labels": sorted(all_labels),
"permissions": permissions,
"recommendations": recommendations,
}
def _deep_copy_section(section: Dict[str, Any]) -> Dict[str, Any]:
"""Create a deep copy of a section dict."""
copy = {
"title": section["title"],
"labels": list(section.get("labels", [])),
}
if "description" in section:
copy["description"] = section["description"]
if "children" in section:
copy["children"] = [_deep_copy_section(child) for child in section["children"]]
return copy
def _slugify(text: str) -> str:
"""Convert text to a URL-safe slug."""
return text.lower().replace(" ", "-").replace("_", "-")
def _generate_space_key(team_name: str) -> str:
"""Generate a space key from team name."""
words = team_name.upper().split()
if len(words) == 1:
return words[0][:10]
return "".join(w[0] for w in words[:5])
def _collect_labels(pages: List[Dict], labels: set) -> None:
"""Recursively collect all labels from page tree."""
for page in pages:
for label in page.get("labels", []):
labels.add(label)
children = page.get("children", [])
if children:
_collect_labels(children, labels)
def _count_pages(pages: List[Dict]) -> int:
"""Count total pages in tree."""
count = len(pages)
for page in pages:
children = page.get("children", [])
if children:
count += _count_pages(children)
return count
def _generate_recommendations(
team_name: str,
team_type: str,
team_size: int,
projects: List,
) -> List[str]:
"""Generate setup recommendations."""
recs = []
recs.append(f"Create the space with key '{_generate_space_key(team_name)}' and enable the blog feature for announcements.")
if team_size > 10:
recs.append("Large team detected. Consider sub-spaces or restricted sections for sub-teams.")
if team_size <= 3:
recs.append("Small team. Simplify the structure by merging low-traffic sections.")
if len(projects) > 5:
recs.append("Many projects listed. Consider a separate space per project for better isolation.")
if team_type == "engineering":
recs.append("Set up page templates for ADRs, runbooks, and design docs.")
recs.append("Enable the Jira macro on Architecture pages for traceability.")
elif team_type == "product":
recs.append("Set up page templates for feature specs and user research notes.")
recs.append("Link roadmap pages to Jira epics for real-time status.")
elif team_type == "marketing":
recs.append("Enable the calendar macro on the Content Calendar page.")
recs.append("Use labels consistently to enable filtered content views.")
recs.append("Review and update space permissions quarterly.")
recs.append("Archive pages older than 6 months that are no longer actively referenced.")
return recs
# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------
def _format_page_tree(pages: List[Dict], indent: int = 0) -> List[str]:
"""Format page tree as indented text."""
lines = []
prefix = " " * indent
for page in pages:
title = page["title"]
labels = page.get("labels", [])
label_str = f" [{', '.join(labels)}]" if labels else ""
lines.append(f"{prefix}|- {title}{label_str}")
if page.get("description"):
lines.append(f"{prefix} {page['description']}")
children = page.get("children", [])
if children:
lines.extend(_format_page_tree(children, indent + 1))
return lines
def format_text_output(result: Dict[str, Any]) -> str:
"""Format results as readable text report."""
lines = []
lines.append("=" * 60)
lines.append("CONFLUENCE SPACE STRUCTURE")
lines.append("=" * 60)
lines.append("")
lines.append("SPACE INFO")
lines.append("-" * 30)
lines.append(f"Space Name: {result['space_name']}")
lines.append(f"Space Key: {result['space_key']}")
lines.append(f"Team Type: {result['team_type'].title()}")
lines.append(f"Team Size: {result['team_size']}")
lines.append(f"Total Pages: {result['total_pages']}")
lines.append("")
lines.append("PAGE TREE")
lines.append("-" * 30)
lines.extend(_format_page_tree(result["page_tree"]))
lines.append("")
lines.append("LABELS")
lines.append("-" * 30)
lines.append(", ".join(result["labels"]))
lines.append("")
permissions = result.get("permissions", {})
if permissions:
lines.append("PERMISSION SUGGESTIONS")
lines.append("-" * 30)
lines.append(f"Admins: {', '.join(permissions.get('admins', []))}")
lines.append(f"Contributors: {', '.join(permissions.get('contributors', []))}")
lines.append(f"Viewers: {', '.join(permissions.get('viewers', []))}")
for restriction in permissions.get("restrictions", []):
lines.append(f" - {restriction}")
lines.append("")
recommendations = result.get("recommendations", [])
if recommendations:
lines.append("RECOMMENDATIONS")
lines.append("-" * 30)
for i, rec in enumerate(recommendations, 1):
lines.append(f"{i}. {rec}")
return "\n".join(lines)
def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
"""Format results as JSON."""
return result
# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------
def main() -> int:
"""Main CLI entry point."""
parser = argparse.ArgumentParser(
description="Generate Confluence space hierarchy from team/project description"
)
parser.add_argument(
"team_file",
help="JSON file with team info (name, size, type, projects)",
)
parser.add_argument(
"--format",
choices=["text", "json"],
default="text",
help="Output format (default: text)",
)
args = parser.parse_args()
try:
with open(args.team_file, "r") as f:
data = json.load(f)
result = generate_space_structure(data)
if args.format == "json":
print(json.dumps(format_json_output(result), indent=2))
else:
print(format_text_output(result))
return 0
except FileNotFoundError:
print(f"Error: File '{args.team_file}' not found", file=sys.stderr)
return 1
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON in '{args.team_file}': {e}", file=sys.stderr)
return 1
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

5
project-management/jira-expert/SKILL.md
View File

@@ -298,3 +298,8 @@ mcp jira create_filter --name "Open Blockers" --jql "priority = Blocker AND stat
- Configure sprint boards for Scrum Master - Configure sprint boards for Scrum Master
- Create documentation pages for Confluence Expert - Create documentation pages for Confluence Expert
- Support template creation for Template Creator - Support template creation for Template Creator
## Related Skills
- **Confluence Expert** (`project-management/confluence-expert/`) — Documentation complements Jira workflows
- **Atlassian Admin** (`project-management/atlassian-admin/`) — Permission and user management for Jira projects

494
project-management/jira-expert/scripts/jql_query_builder.py Normal file
View File

@@ -0,0 +1,494 @@
#!/usr/bin/env python3
"""
JQL Query Builder
Pattern-matching JQL builder from natural language descriptions. Maps common
phrases to JQL operators and constructs valid queries with syntax validation.
Usage:
python jql_query_builder.py "high priority bugs in PROJECT assigned to me"
python jql_query_builder.py "overdue tasks in PROJ" --format json
python jql_query_builder.py --patterns
"""
import argparse
import json
import re
import sys
from datetime import datetime
from typing import Any, Dict, List, Optional, Tuple
# ---------------------------------------------------------------------------
# Pattern Library
# ---------------------------------------------------------------------------
PATTERN_LIBRARY = {
"my_open_bugs": {
"phrases": ["my open bugs", "my bugs", "bugs assigned to me"],
"jql": 'assignee = currentUser() AND type = Bug AND status != Done',
"description": "All open bugs assigned to current user",
},
"high_priority_bugs": {
"phrases": ["high priority bugs", "critical bugs", "urgent bugs", "p1 bugs"],
"jql": 'type = Bug AND priority in (Highest, High) AND status != Done',
"description": "High and highest priority open bugs",
},
"my_open_tasks": {
"phrases": ["my open tasks", "my tasks", "tasks assigned to me", "my work"],
"jql": 'assignee = currentUser() AND status != Done',
"description": "All open issues assigned to current user",
},
"unassigned_issues": {
"phrases": ["unassigned", "unassigned issues", "no assignee"],
"jql": 'assignee is EMPTY AND status != Done',
"description": "Issues with no assignee",
},
"recently_created": {
"phrases": ["recently created", "new issues", "created this week", "recent"],
"jql": 'created >= -7d ORDER BY created DESC',
"description": "Issues created in the last 7 days",
},
"recently_updated": {
"phrases": ["recently updated", "updated this week", "recent changes"],
"jql": 'updated >= -7d ORDER BY updated DESC',
"description": "Issues updated in the last 7 days",
},
"overdue": {
"phrases": ["overdue", "past due", "missed deadline", "overdue tasks"],
"jql": 'duedate < now() AND status != Done',
"description": "Issues past their due date",
},
"due_this_week": {
"phrases": ["due this week", "due soon", "upcoming deadlines"],
"jql": 'duedate >= startOfWeek() AND duedate <= endOfWeek() AND status != Done',
"description": "Issues due this week",
},
"blocked_issues": {
"phrases": ["blocked", "blocked issues", "impediments"],
"jql": 'status = Blocked OR status = Impediment',
"description": "Issues in blocked or impediment status",
},
"in_progress": {
"phrases": ["in progress", "being worked on", "active work"],
"jql": 'status = "In Progress"',
"description": "Issues currently in progress",
},
"sprint_issues": {
"phrases": ["current sprint", "this sprint", "active sprint"],
"jql": 'sprint in openSprints()',
"description": "Issues in the current active sprint",
},
"backlog": {
"phrases": ["backlog", "backlog items", "not started"],
"jql": 'sprint is EMPTY AND status = "To Do" ORDER BY priority DESC',
"description": "Issues in the backlog not assigned to a sprint",
},
"stories_without_estimates": {
"phrases": ["no estimates", "unestimated", "missing estimates", "no story points"],
"jql": 'type = Story AND (storyPoints is EMPTY OR storyPoints = 0) AND status != Done',
"description": "Stories missing story point estimates",
},
"epics_in_progress": {
"phrases": ["active epics", "epics in progress", "open epics"],
"jql": 'type = Epic AND status != Done ORDER BY priority DESC',
"description": "Epics that are not yet completed",
},
"done_this_week": {
"phrases": ["done this week", "completed this week", "resolved this week"],
"jql": 'status changed to Done DURING (startOfWeek(), now())',
"description": "Issues completed during the current week",
},
"created_vs_resolved": {
"phrases": ["created vs resolved", "issue flow", "throughput"],
"jql": 'created >= -30d ORDER BY created DESC',
"description": "Issues created in the last 30 days for flow analysis",
},
"my_reported_issues": {
"phrases": ["my reported", "reported by me", "i created", "i reported"],
"jql": 'reporter = currentUser() ORDER BY created DESC',
"description": "Issues reported by current user",
},
"stale_issues": {
"phrases": ["stale", "stale issues", "not updated", "abandoned"],
"jql": 'updated <= -30d AND status != Done ORDER BY updated ASC',
"description": "Issues not updated in 30+ days",
},
"subtasks_without_parent": {
"phrases": ["orphan subtasks", "subtasks no parent", "loose subtasks"],
"jql": 'type = Sub-task AND parent is EMPTY',
"description": "Subtasks missing parent issues",
},
"high_priority_unassigned": {
"phrases": ["high priority unassigned", "urgent unassigned", "critical no owner"],
"jql": 'priority in (Highest, High) AND assignee is EMPTY AND status != Done',
"description": "High priority issues with no assignee",
},
"bugs_by_component": {
"phrases": ["bugs by component", "component bugs"],
"jql": 'type = Bug AND status != Done ORDER BY component ASC',
"description": "Open bugs organized by component",
},
"resolved_recently": {
"phrases": ["resolved recently", "recently resolved", "fixed this month"],
"jql": 'resolved >= -30d ORDER BY resolved DESC',
"description": "Issues resolved in the last 30 days",
},
}
# Keyword-to-JQL fragment mapping for dynamic query building
KEYWORD_FRAGMENTS = {
# Issue types
"bug": ("type", "= Bug"),
"bugs": ("type", "= Bug"),
"story": ("type", "= Story"),
"stories": ("type", "= Story"),
"task": ("type", "= Task"),
"tasks": ("type", "= Task"),
"epic": ("type", "= Epic"),
"epics": ("type", "= Epic"),
"subtask": ("type", "= Sub-task"),
"sub-task": ("type", "= Sub-task"),
# Statuses
"open": ("status", "!= Done"),
"closed": ("status", "= Done"),
"done": ("status", "= Done"),
"resolved": ("status", "= Done"),
"todo": ("status", '= "To Do"'),
# Priorities
"critical": ("priority", "= Highest"),
"highest": ("priority", "= Highest"),
"high": ("priority", "in (Highest, High)"),
"medium": ("priority", "= Medium"),
"low": ("priority", "in (Low, Lowest)"),
"lowest": ("priority", "= Lowest"),
# Assignee
"me": ("assignee", "= currentUser()"),
"mine": ("assignee", "= currentUser()"),
"unassigned": ("assignee", "is EMPTY"),
# Time
"overdue": ("duedate", "< now()"),
"today": ("duedate", "= now()"),
}
PROJECT_PATTERN = re.compile(r'\b([A-Z]{2,10})\b')
ASSIGNEE_PATTERN = re.compile(r'assigned\s+to\s+(\w+)', re.IGNORECASE)
LABEL_PATTERN = re.compile(r'label[s]?\s*[=:]\s*["\']?(\w+)["\']?', re.IGNORECASE)
COMPONENT_PATTERN = re.compile(r'component[s]?\s*[=:]\s*["\']?(\w+)["\']?', re.IGNORECASE)
DATE_RANGE_PATTERN = re.compile(r'last\s+(\d+)\s+(day|week|month)s?', re.IGNORECASE)
SPRINT_NAME_PATTERN = re.compile(r'sprint\s+["\']?(\w[\w\s]*\w)["\']?', re.IGNORECASE)
# Words to exclude from project matching
EXCLUDED_WORDS = {
"AND", "OR", "NOT", "IN", "IS", "TO", "BY", "ON", "DO", "BE",
"THE", "ALL", "MY", "NO", "OF", "AT", "AS", "IF", "IT",
"BUG", "BUGS", "TASK", "TASKS", "STORY", "EPIC", "DONE",
"HIGH", "LOW", "MEDIUM", "JQL",
}
# ---------------------------------------------------------------------------
# Query Builder
# ---------------------------------------------------------------------------
def find_matching_pattern(description: str) -> Optional[Dict[str, Any]]:
"""Check if description matches a known pattern exactly."""
desc_lower = description.lower().strip()
for pattern_name, pattern_data in PATTERN_LIBRARY.items():
for phrase in pattern_data["phrases"]:
if phrase in desc_lower or desc_lower in phrase:
return {
"pattern_name": pattern_name,
"jql": pattern_data["jql"],
"description": pattern_data["description"],
"match_type": "exact_pattern",
}
return None
def build_jql_from_description(description: str) -> Dict[str, Any]:
"""Build JQL query from natural language description."""
# First try exact pattern match
pattern_match = find_matching_pattern(description)
if pattern_match:
# Augment with project if mentioned
project = _extract_project(description)
if project:
pattern_match["jql"] = f'project = {project} AND {pattern_match["jql"]}'
return pattern_match
# Dynamic query building
clauses = []
used_fields = set()
desc_lower = description.lower()
# Extract project
project = _extract_project(description)
if project:
clauses.append(f"project = {project}")
used_fields.add("project")
# Extract keyword-based fragments
for keyword, (field, fragment) in KEYWORD_FRAGMENTS.items():
if keyword in desc_lower.split() and field not in used_fields:
clauses.append(f"{field} {fragment}")
used_fields.add(field)
# Extract explicit assignee
assignee_match = ASSIGNEE_PATTERN.search(description)
if assignee_match and "assignee" not in used_fields:
assignee = assignee_match.group(1)
if assignee.lower() in ("me", "myself"):
clauses.append("assignee = currentUser()")
else:
clauses.append(f'assignee = "{assignee}"')
used_fields.add("assignee")
# Extract labels
label_match = LABEL_PATTERN.search(description)
if label_match:
clauses.append(f'labels = "{label_match.group(1)}"')
# Extract component
component_match = COMPONENT_PATTERN.search(description)
if component_match:
clauses.append(f'component = "{component_match.group(1)}"')
# Extract date ranges
date_match = DATE_RANGE_PATTERN.search(description)
if date_match:
amount = date_match.group(1)
unit = date_match.group(2).lower()
unit_char = {"day": "d", "week": "w", "month": "m"}.get(unit, "d")
clauses.append(f"created >= -{amount}{unit_char}")
# Extract sprint reference
sprint_match = SPRINT_NAME_PATTERN.search(description)
if sprint_match:
sprint_name = sprint_match.group(1).strip()
if sprint_name.lower() in ("current", "active", "open"):
clauses.append("sprint in openSprints()")
else:
clauses.append(f'sprint = "{sprint_name}"')
# Default: if no status clause and not looking for done items
if "status" not in used_fields and "done" not in desc_lower and "closed" not in desc_lower:
clauses.append("status != Done")
if not clauses:
return {
"jql": "",
"description": "Could not build query from description",
"match_type": "no_match",
"error": "No recognizable patterns found in description",
}
jql = " AND ".join(clauses)
# Add ORDER BY for common scenarios
if "recent" in desc_lower or "latest" in desc_lower:
jql += " ORDER BY created DESC"
elif "priority" in desc_lower or "urgent" in desc_lower:
jql += " ORDER BY priority DESC"
return {
"jql": jql,
"description": f"Dynamic query from: {description}",
"match_type": "dynamic",
"clauses_used": len(clauses),
}
def _extract_project(description: str) -> Optional[str]:
"""Extract project key from description."""
# Look for IN/in PROJECT pattern
in_project = re.search(r'\bin\s+([A-Z]{2,10})\b', description)
if in_project and in_project.group(1) not in EXCLUDED_WORDS:
return in_project.group(1)
# Look for standalone project keys
for match in PROJECT_PATTERN.finditer(description):
word = match.group(1)
if word not in EXCLUDED_WORDS:
return word
return None
def validate_jql_syntax(jql: str) -> Dict[str, Any]:
"""Basic JQL syntax validation."""
issues = []
if not jql.strip():
return {"valid": False, "issues": ["Empty query"]}
# Check balanced quotes
single_quotes = jql.count("'")
double_quotes = jql.count('"')
if single_quotes % 2 != 0:
issues.append("Unbalanced single quotes")
if double_quotes % 2 != 0:
issues.append("Unbalanced double quotes")
# Check balanced parentheses
open_parens = jql.count("(")
close_parens = jql.count(")")
if open_parens != close_parens:
issues.append(f"Unbalanced parentheses: {open_parens} open, {close_parens} close")
# Check for known JQL operators
valid_operators = {"=", "!=", ">", "<", ">=", "<=", "~", "!~", "in", "not in", "is", "is not", "was", "was not", "changed"}
jql_upper = jql.upper()
# Check AND/OR placement
if jql_upper.strip().startswith("AND") or jql_upper.strip().startswith("OR"):
issues.append("Query cannot start with AND/OR")
if jql_upper.strip().endswith("AND") or jql_upper.strip().endswith("OR"):
issues.append("Query cannot end with AND/OR")
# Check ORDER BY syntax
order_match = re.search(r'ORDER\s+BY\s+(\w+)(?:\s+(ASC|DESC))?', jql, re.IGNORECASE)
if "ORDER" in jql_upper and not order_match:
issues.append("Invalid ORDER BY syntax")
return {
"valid": len(issues) == 0,
"issues": issues,
"query_length": len(jql),
}
# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------
def format_text_output(result: Dict[str, Any]) -> str:
"""Format results as readable text report."""
lines = []
lines.append("=" * 60)
lines.append("JQL QUERY BUILDER RESULTS")
lines.append("=" * 60)
lines.append("")
if "error" in result:
lines.append(f"ERROR: {result['error']}")
return "\n".join(lines)
lines.append(f"Match Type: {result.get('match_type', 'unknown')}")
lines.append(f"Description: {result.get('description', '')}")
lines.append("")
lines.append("GENERATED JQL")
lines.append("-" * 30)
lines.append(result.get("jql", ""))
lines.append("")
validation = result.get("validation", {})
if validation:
lines.append("VALIDATION")
lines.append("-" * 30)
lines.append(f"Valid: {'Yes' if validation.get('valid') else 'No'}")
if validation.get("issues"):
for issue in validation["issues"]:
lines.append(f" - {issue}")
if result.get("pattern_name"):
lines.append("")
lines.append(f"Matched Pattern: {result['pattern_name']}")
return "\n".join(lines)
def format_patterns_output(output_format: str) -> str:
"""Format available patterns list."""
if output_format == "json":
patterns = {}
for name, data in PATTERN_LIBRARY.items():
patterns[name] = {
"description": data["description"],
"phrases": data["phrases"],
"jql": data["jql"],
}
return json.dumps(patterns, indent=2)
lines = []
lines.append("=" * 60)
lines.append("AVAILABLE JQL PATTERNS")
lines.append("=" * 60)
lines.append("")
for name, data in PATTERN_LIBRARY.items():
lines.append(f" {name}")
lines.append(f" Description: {data['description']}")
lines.append(f" Phrases: {', '.join(data['phrases'])}")
lines.append(f" JQL: {data['jql']}")
lines.append("")
lines.append(f"Total patterns: {len(PATTERN_LIBRARY)}")
return "\n".join(lines)
def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
"""Format results as JSON."""
return result
# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------
def main() -> int:
"""Main CLI entry point."""
parser = argparse.ArgumentParser(
description="Build JQL queries from natural language descriptions"
)
parser.add_argument(
"description",
nargs="?",
help="Natural language description of the query",
)
parser.add_argument(
"--format",
choices=["text", "json"],
default="text",
help="Output format (default: text)",
)
parser.add_argument(
"--patterns",
action="store_true",
help="List all available query patterns",
)
args = parser.parse_args()
try:
if args.patterns:
print(format_patterns_output(args.format))
return 0
if not args.description:
parser.error("description is required unless --patterns is used")
# Build query
result = build_jql_from_description(args.description)
# Validate
if result.get("jql"):
result["validation"] = validate_jql_syntax(result["jql"])
# Output results
if args.format == "json":
output = format_json_output(result)
print(json.dumps(output, indent=2))
else:
output = format_text_output(result)
print(output)
return 0
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

424
project-management/jira-expert/scripts/workflow_validator.py Normal file
View File

@@ -0,0 +1,424 @@
#!/usr/bin/env python3
"""
Workflow Validator
Validates Jira workflow definitions (JSON input) for anti-patterns and common
issues. Checks for dead-end states, orphan states, missing transitions, circular
paths, and produces a health score with severity-rated findings.
Usage:
python workflow_validator.py workflow.json
python workflow_validator.py workflow.json --format json
"""
import argparse
import json
import sys
from typing import Any, Dict, List, Optional, Set, Tuple
# ---------------------------------------------------------------------------
# Validation Configuration
# ---------------------------------------------------------------------------
MAX_RECOMMENDED_STATES = 10
REQUIRED_TERMINAL_STATES = {"done", "closed", "resolved", "completed"}
SEVERITY_WEIGHTS = {
"error": 20,
"warning": 10,
"info": 3,
}
# ---------------------------------------------------------------------------
# Validation Rules
# ---------------------------------------------------------------------------
def check_state_count(states: List[str]) -> List[Dict[str, str]]:
"""Check if the workflow has too many states."""
findings = []
count = len(states)
if count > MAX_RECOMMENDED_STATES:
findings.append({
"rule": "state_count",
"severity": "warning",
"message": f"Workflow has {count} states (recommended max: {MAX_RECOMMENDED_STATES}). "
f"Complex workflows slow teams down and increase error rates.",
})
elif count < 2:
findings.append({
"rule": "state_count",
"severity": "error",
"message": f"Workflow has only {count} state(s). A minimum of 2 states is required.",
})
if count > 15:
findings[-1]["severity"] = "error"
return findings
def check_dead_end_states(
states: List[str],
transitions: List[Dict[str, str]],
terminal_states: Set[str],
) -> List[Dict[str, str]]:
"""Find states with no outgoing transitions that are not terminal."""
findings = []
outgoing = set()
for t in transitions:
outgoing.add(t.get("from", "").lower())
for state in states:
state_lower = state.lower()
if state_lower not in outgoing and state_lower not in terminal_states:
findings.append({
"rule": "dead_end_state",
"severity": "error",
"message": f"State '{state}' has no outgoing transitions and is not a terminal state. "
f"Issues will get stuck here.",
})
return findings
def check_orphan_states(
states: List[str],
transitions: List[Dict[str, str]],
initial_state: Optional[str],
) -> List[Dict[str, str]]:
"""Find states with no incoming transitions (except the initial state)."""
findings = []
incoming = set()
for t in transitions:
incoming.add(t.get("to", "").lower())
initial_lower = (initial_state or "").lower()
for state in states:
state_lower = state.lower()
if state_lower not in incoming and state_lower != initial_lower:
findings.append({
"rule": "orphan_state",
"severity": "warning",
"message": f"State '{state}' has no incoming transitions and is not the initial state. "
f"This state may be unreachable.",
})
return findings
def check_missing_terminal_state(states: List[str]) -> List[Dict[str, str]]:
"""Check that at least one terminal/done state exists."""
findings = []
states_lower = {s.lower() for s in states}
has_terminal = bool(states_lower & REQUIRED_TERMINAL_STATES)
if not has_terminal:
findings.append({
"rule": "missing_terminal_state",
"severity": "error",
"message": f"No terminal state found. Expected one of: {', '.join(sorted(REQUIRED_TERMINAL_STATES))}. "
f"Issues cannot be marked as complete.",
})
return findings
def check_duplicate_transition_names(
transitions: List[Dict[str, str]],
) -> List[Dict[str, str]]:
"""Check for duplicate transition names from the same state."""
findings = []
seen = {}
for t in transitions:
name = t.get("name", "").lower()
from_state = t.get("from", "").lower()
key = (from_state, name)
if key in seen:
findings.append({
"rule": "duplicate_transition",
"severity": "warning",
"message": f"Duplicate transition name '{t.get('name', '')}' from state '{t.get('from', '')}'. "
f"This can confuse users selecting transitions.",
})
else:
seen[key] = True
return findings
def check_missing_transitions(
states: List[str],
transitions: List[Dict[str, str]],
) -> List[Dict[str, str]]:
"""Check for states referenced in transitions but not defined."""
findings = []
defined_states = {s.lower() for s in states}
for t in transitions:
from_state = t.get("from", "").lower()
to_state = t.get("to", "").lower()
if from_state and from_state not in defined_states:
findings.append({
"rule": "undefined_state_reference",
"severity": "error",
"message": f"Transition references undefined source state '{t.get('from', '')}'.",
})
if to_state and to_state not in defined_states:
findings.append({
"rule": "undefined_state_reference",
"severity": "error",
"message": f"Transition references undefined target state '{t.get('to', '')}'.",
})
return findings
def check_circular_paths(
states: List[str],
transitions: List[Dict[str, str]],
terminal_states: Set[str],
) -> List[Dict[str, str]]:
"""Detect circular paths that have no exit to a terminal state."""
findings = []
# Build adjacency list
adjacency = {}
for state in states:
adjacency[state.lower()] = set()
for t in transitions:
from_state = t.get("from", "").lower()
to_state = t.get("to", "").lower()
if from_state in adjacency:
adjacency[from_state].add(to_state)
# Find strongly connected components using iterative DFS
def can_reach_terminal(start: str) -> bool:
visited = set()
stack = [start]
while stack:
node = stack.pop()
if node in terminal_states:
return True
if node in visited:
continue
visited.add(node)
for neighbor in adjacency.get(node, set()):
stack.append(neighbor)
return False
# Check each non-terminal state
for state in states:
state_lower = state.lower()
if state_lower not in terminal_states:
if not can_reach_terminal(state_lower):
findings.append({
"rule": "circular_no_exit",
"severity": "error",
"message": f"State '{state}' cannot reach any terminal state. "
f"Issues entering this state will never be resolved.",
})
return findings
def check_self_transitions(transitions: List[Dict[str, str]]) -> List[Dict[str, str]]:
"""Check for transitions that go from a state to itself."""
findings = []
for t in transitions:
if t.get("from", "").lower() == t.get("to", "").lower():
findings.append({
"rule": "self_transition",
"severity": "info",
"message": f"State '{t.get('from', '')}' has a self-transition '{t.get('name', '')}'. "
f"Ensure this is intentional (e.g., for triggering automation).",
})
return findings
# ---------------------------------------------------------------------------
# Main Validation
# ---------------------------------------------------------------------------
def validate_workflow(data: Dict[str, Any]) -> Dict[str, Any]:
"""Run all validations on a workflow definition."""
states = data.get("states", [])
transitions = data.get("transitions", [])
initial_state = data.get("initial_state", states[0] if states else None)
if not states:
return {
"health_score": 0,
"grade": "invalid",
"findings": [{"rule": "no_states", "severity": "error", "message": "No states defined in workflow"}],
"summary": {"errors": 1, "warnings": 0, "info": 0},
}
# Determine terminal states
states_lower = {s.lower() for s in states}
terminal_states = states_lower & REQUIRED_TERMINAL_STATES
# Custom terminal states from input
custom_terminals = data.get("terminal_states", [])
for ct in custom_terminals:
terminal_states.add(ct.lower())
# Run all checks
all_findings = []
all_findings.extend(check_state_count(states))
all_findings.extend(check_dead_end_states(states, transitions, terminal_states))
all_findings.extend(check_orphan_states(states, transitions, initial_state))
all_findings.extend(check_missing_terminal_state(states))
all_findings.extend(check_duplicate_transition_names(transitions))
all_findings.extend(check_missing_transitions(states, transitions))
all_findings.extend(check_circular_paths(states, transitions, terminal_states))
all_findings.extend(check_self_transitions(transitions))
# Calculate health score
summary = {"errors": 0, "warnings": 0, "info": 0}
penalty = 0
for finding in all_findings:
severity = finding["severity"]
summary[severity] = summary.get(severity, 0) + 1
penalty += SEVERITY_WEIGHTS.get(severity, 0)
health_score = max(0, 100 - penalty)
if health_score >= 90:
grade = "excellent"
elif health_score >= 75:
grade = "good"
elif health_score >= 55:
grade = "fair"
else:
grade = "poor"
return {
"health_score": health_score,
"grade": grade,
"findings": all_findings,
"summary": summary,
"workflow_info": {
"state_count": len(states),
"transition_count": len(transitions),
"initial_state": initial_state,
"terminal_states": sorted(terminal_states),
},
}
# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------
def format_text_output(result: Dict[str, Any]) -> str:
"""Format results as readable text report."""
lines = []
lines.append("=" * 60)
lines.append("WORKFLOW VALIDATION REPORT")
lines.append("=" * 60)
lines.append("")
# Health summary
lines.append("HEALTH SUMMARY")
lines.append("-" * 30)
lines.append(f"Health Score: {result['health_score']}/100")
lines.append(f"Grade: {result['grade'].title()}")
lines.append("")
# Workflow info
info = result.get("workflow_info", {})
if info:
lines.append("WORKFLOW INFO")
lines.append("-" * 30)
lines.append(f"States: {info.get('state_count', 0)}")
lines.append(f"Transitions: {info.get('transition_count', 0)}")
lines.append(f"Initial State: {info.get('initial_state', 'N/A')}")
lines.append(f"Terminal States: {', '.join(info.get('terminal_states', []))}")
lines.append("")
# Summary
summary = result.get("summary", {})
lines.append("FINDINGS SUMMARY")
lines.append("-" * 30)
lines.append(f"Errors: {summary.get('errors', 0)}")
lines.append(f"Warnings: {summary.get('warnings', 0)}")
lines.append(f"Info: {summary.get('info', 0)}")
lines.append("")
# Detailed findings
findings = result.get("findings", [])
if findings:
lines.append("DETAILED FINDINGS")
lines.append("-" * 30)
for i, finding in enumerate(findings, 1):
severity = finding["severity"].upper()
lines.append(f"{i}. [{severity}] {finding['message']}")
lines.append(f" Rule: {finding['rule']}")
lines.append("")
else:
lines.append("No issues found. Workflow looks healthy!")
return "\n".join(lines)
def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
"""Format results as JSON."""
return result
# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------
def main() -> int:
"""Main CLI entry point."""
parser = argparse.ArgumentParser(
description="Validate Jira workflow definitions for anti-patterns"
)
parser.add_argument(
"workflow_file",
help="JSON file containing workflow definition (states, transitions)",
)
parser.add_argument(
"--format",
choices=["text", "json"],
default="text",
help="Output format (default: text)",
)
args = parser.parse_args()
try:
with open(args.workflow_file, "r") as f:
data = json.load(f)
result = validate_workflow(data)
if args.format == "json":
print(json.dumps(format_json_output(result), indent=2))
else:
print(format_text_output(result))
return 0
except FileNotFoundError:
print(f"Error: File '{args.workflow_file}' not found", file=sys.stderr)
return 1
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON in '{args.workflow_file}': {e}", file=sys.stderr)
return 1
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

7
project-management/scrum-master/SKILL.md
View File

@@ -212,4 +212,11 @@ Apply stage-specific facilitation (details in `references/team-dynamics-framewor
--- ---
## Related Skills
- **Agile Product Owner** (`product-team/agile-product-owner/`) — User stories and backlog feed sprint planning
- **Senior PM** (`project-management/senior-pm/`) — Portfolio health context informs sprint priorities
---
*For deep framework references see `references/velocity-forecasting-guide.md` and `references/team-dynamics-framework.md`. For template assets see `assets/sprint_report_template.md` and `assets/team_health_check_template.md`.* *For deep framework references see `references/velocity-forecasting-guide.md` and `references/team-dynamics-framework.md`. For template assets see `assets/sprint_report_template.md` and `assets/team_health_check_template.md`.*

5
project-management/senior-pm/SKILL.md
View File

@@ -401,3 +401,8 @@ Reference: `references/portfolio-kpis.md` for full definitions and measurement g
- Executive interview feedback on decision support quality - Executive interview feedback on decision support quality
- Team feedback on process efficiency and effectiveness - Team feedback on process efficiency and effectiveness
- Customer impact assessment of portfolio decisions - Customer impact assessment of portfolio decisions
## Related Skills
- **Product Strategist** (`product-team/product-strategist/`) — Product OKRs align with portfolio objectives
- **Scrum Master** (`project-management/scrum-master/`) — Sprint velocity data feeds project health dashboards