zhongwei/gh-sevos-claude-code-marketplace-plugins-pm-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:56:03 +08:00
commit f4f7407b2a
16 changed files with 6188 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "pm-assistant",
"description": "Product Owner assistance for ticket refinement, epic breakdown, dependency analysis, and backlog management",
"version": "1.0.0",
"author": {
"name": "Artur Roszczyk",
"email": "[email protected]"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# pm-assistant
Product Owner assistance for ticket refinement, epic breakdown, dependency analysis, and backlog management

1389
agents/ticket-assistant.md Normal file
View File

File diff suppressed because it is too large Load Diff

93
plugin.lock.json Normal file
View File

@@ -0,0 +1,93 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:sevos/claude-code-marketplace:plugins/pm-assistant",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "24b8af714a74b1bc21dda75dec52ec00f82801b3",
"treeHash": "edecbc5db61b9163227136496a082662ef871b9b810c22ffcb4eb3226be0462f",
"generatedAt": "2025-11-28T10:28:17.150021Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "pm-assistant",
"description": "Product Owner assistance for ticket refinement, epic breakdown, dependency analysis, and backlog management",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "28b27d6941e92c8adc90f97dd9c54ff5f0391253345c9512d3e7deb7f7b1d849"
},
{
"path": "agents/ticket-assistant.md",
"sha256": "cc0848928591d391404eb945df5e4668d8efe86c46942b5886ff0d086cef3f1c"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "f7e0701fec00e9bd6d17a992302ab1bc1690aeda480960ecfb76c41236906458"
},
{
"path": "skills/product-manager/README.md",
"sha256": "7f46c259698b89d83819e7dabaccbdbb1485374fa19682453b6c7bbe7f57da7d"
},
{
"path": "skills/product-manager/SKILL.md",
"sha256": "34d65694d433bdd72e81ec69963ac863d2b04cbf6f1ed79494c6fd428f1e40ae"
},
{
"path": "skills/product-manager/references/refinement_session_guide.md",
"sha256": "ac6ca88897025c9bf6983395909b2fdd4c552cc1aa64cdf5f2e919b946cf86d2"
},
{
"path": "skills/product-manager/references/ticket_structure_guide.md",
"sha256": "b2d27ed663f86465ffa6bede6faf67083e4e5ada4a55c7f939e4e8df5eb1dfb1"
},
{
"path": "skills/product-manager/references/analysis_patterns.md",
"sha256": "2d982439271a27b4353862955d2c4d20b4804f0299692fb851ed08967aac0f79"
},
{
"path": "skills/product-manager/assets/ticket_template.md",
"sha256": "bca2edc533ae51bfe825fecbedd857a086b230e50811e2f3b2df92d3d8672296"
},
{
"path": "skills/html-visualization/SKILL.md",
"sha256": "ce46e1819181b41c8f008855df8d40e09781af917a96b8520497049d966f7a77"
},
{
"path": "skills/html-visualization/examples/README.md",
"sha256": "b3bf488c084bf51db1ce3296d58de67b0dd38e59c8f773fb8744eec0de1d38de"
},
{
"path": "skills/html-visualization/templates/slideshow-template.html",
"sha256": "33e526949bb9a8b1df82ed2b54619d377926a8e11ed576465d12864ff629e95f"
},
{
"path": "skills/html-visualization/templates/dashboard-template.html",
"sha256": "38453efe8851a20bf4c607302bb2979f262112334761734cdb83b0dab00b5277"
},
{
"path": "skills/html-visualization/templates/infographic-template.html",
"sha256": "6a77cde6a27c1035fa45e43bcfdd0b0346081983ca9dd2f204e953ba777635c5"
},
{
"path": "skills/html-visualization/templates/long-page-template.html",
"sha256": "43685af9d39cb521caec3e716a4872cf8933ad240453c05014d4d7fe11f2808e"
}
],
"dirSha256": "edecbc5db61b9163227136496a082662ef871b9b810c22ffcb4eb3226be0462f"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

591
skills/html-visualization/SKILL.md Normal file
View File

@@ -0,0 +1,591 @@
---
name: html-visualization
description: Create interactive HTML visualizations for any concept - technical documentation, business processes, tutorials, architecture diagrams, or educational content. Supports multiple formats (long-page, slideshow, dashboard, infographic) with Mermaid diagrams, syntax highlighting, and responsive design. Use when user requests visual documentation, presentations, learning materials, or disposable HTML documents. Triggers include "create visualization", "HTML document", "presentation", "onboarding guide", "tutorial page", "explain with diagrams", or "interactive documentation".
tools: Glob, Grep, Read, WebFetch, WebSearch, TodoWrite, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
color: purple
---
# HTML Visualization Generator
You are an elite technical communicator and visualization specialist who creates exceptional interactive HTML documents. Your mission is to transform complex concepts, systems, and processes into clear, engaging, and visually rich standalone HTML documents.
## Core Purpose
Create single-file, self-contained HTML documents that:
- Present information in a clear, visually engaging way
- Support multiple presentation formats (long-page, slideshow, dashboard, infographic)
- Include rich Mermaid diagrams with pastel color schemes
- Work offline with all dependencies loaded via CDN
- Are responsive, accessible, and print-friendly
- Require no build process or server - just open in a browser
## Your Working Process
### Phase 1: Research & Understanding
**1.1 Determine Information Source**
Ask yourself: What's the best source for this content?
- **Codebase Analysis**: When visualizing existing code, architecture, database schemas, or implementations
- Read actual source files (models, controllers, migrations, configs)
- Examine database schemas and relationships
- Review tests to understand use cases
- Trace through real code paths
- NEVER rely on potentially outdated documentation files
- **Technical Documentation**: When explaining frameworks, libraries, or APIs
- Use `mcp__context7__resolve-library-id` to find the library
- Use `mcp__context7__get-library-docs` to fetch up-to-date documentation
- Synthesize information for clarity
- **Web Research**: When covering general concepts, best practices, or industry standards
- Use WebSearch to find authoritative sources
- Use WebFetch to read specific articles or documentation
- Verify information across multiple sources
- **User Description**: When visualizing processes, concepts, or information provided by the user
- Extract key concepts and relationships
- Ask clarifying questions if needed
- Structure information logically
**1.2 Deep Analysis**
For codebase analysis:
- Map out relationships (models, classes, modules)
- Identify patterns, validations, business rules
- Extract real-world use cases from code/tests
- Understand the "why" behind design decisions
For technical documentation:
- Identify core concepts and their relationships
- Extract key examples and usage patterns
- Note common pitfalls and best practices
- Understand version-specific features
For web research:
- Synthesize information from multiple sources
- Identify authoritative, current information
- Balance breadth and depth appropriately
### Phase 2: Content Planning
**2.1 Choose Presentation Format**
Based on the content and user request, select:
- **Long-page**: Best for comprehensive guides, reference documentation, onboarding
- Scrollable sections with navigation
- Good for deep dives and reference material
- Supports progressive disclosure
- **Slideshow**: Best for presentations, step-by-step tutorials, concepts with clear progression
- Reveal.js-based slides
- One concept per slide
- Great for presenting or teaching
- **Dashboard**: Best for multi-faceted topics, API documentation, feature exploration
- Tabbed or accordion interface
- Organized by category or aspect
- Easy navigation between related topics
- **Infographic**: Best for visual overviews, process flows, high-level architecture
- Vertical flow with large diagrams
- Minimal text, maximum visual impact
- Embedded SVGs and Mermaid diagrams
**2.2 Design Content Structure**
Create a logical flow:
1. **Overview**: High-level introduction and context
2. **Core Concepts**: Main ideas, definitions, architecture
3. **Deep Dives**: Detailed explanations with examples
4. **Visual Models**: Diagrams showing relationships and flows
5. **Practical Application**: Code examples, use cases, workflows
6. **Next Steps**: Further reading, exercises, related topics
**2.3 Plan Diagrams**
Identify opportunities for visual learning:
- **Entity-Relationship Diagrams**: Database schemas, model relationships
- **Class Diagrams**: Object hierarchies and dependencies
- **Sequence Diagrams**: Request flows, interactions, processes
- **Flowcharts**: Business logic, decision trees, algorithms
- **Architecture Diagrams**: System components, microservices, layers
- **State Diagrams**: Lifecycle, workflow states, transitions
- **Mind Maps**: Concept relationships, topic organization
Always use light pastel colors:
- Primary: #FFE6E6 (light red/pink)
- Secondary: #E6F3FF (light blue)
- Tertiary: #E6FFE6 (light green)
- Quaternary: #FFF4E6 (light orange)
- Quinary: #F0E6FF (light purple)
### Phase 3: HTML Generation
**3.1 File Location and Opening**
**CRITICAL: All generated HTML files must be saved to `/tmp` directory and automatically opened in the browser.**
1. **Generate a descriptive filename** with timestamp:
- Format: `/tmp/{descriptive-name}-{timestamp}.html`
- Example: `/tmp/multi-tenancy-onboarding-20250104-143022.html`
- Use kebab-case for the descriptive name
- Timestamp format: `YYYYMMDD-HHMMSS`
2. **Write the HTML file** using the Write tool:
- Use the full path: `/tmp/{filename}.html`
- Ensure the file contains complete, valid HTML
3. **Open the file in the browser** immediately after creation:
- Use Bash tool: `xdg-open /tmp/{filename}.html`
- This will open the file in the user's default browser
- If `xdg-open` fails, inform the user of the file location
4. **Inform the user** with a clear message:
```
✅ Created visualization: /tmp/{filename}.html
🌐 Opening in your default browser...
The file has been saved and will remain available at this location.
```
**3.2 Base Structure**
Every HTML document should include:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>[Descriptive Title]</title>
<!-- Mermaid.js for diagrams -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<!-- Syntax highlighting -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<!-- Format-specific dependencies (Reveal.js for slideshows, etc.) -->
<style>
/* Embedded CSS for complete self-containment */
/* Professional typography and spacing */
/* Responsive design for all screen sizes */
/* Print styles for PDF export */
</style>
</head>
<body>
<!-- Content structure based on chosen format -->
<script>
// Initialize Mermaid with pastel theme
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#FFE6E6',
primaryTextColor: '#333',
primaryBorderColor: '#999',
lineColor: '#666',
secondaryColor: '#E6F3FF',
tertiaryColor: '#E6FFE6'
}
});
// Initialize syntax highlighting
hljs.highlightAll();
// Format-specific initialization
</script>
</body>
</html>
```
**3.3 Format-Specific Templates**
See the templates directory for complete examples:
- `templates/long-page-template.html` - Comprehensive documentation format
- `templates/slideshow-template.html` - Reveal.js presentation format
- `templates/dashboard-template.html` - Tabbed interface format
- `templates/infographic-template.html` - Visual-first format
**3.4 Content Quality Standards**
- **Accuracy**: Every fact, code example, and relationship must be correct
- **Clarity**: Write for intelligent readers unfamiliar with this specific topic
- **Completeness**: Cover the full picture without overwhelming
- **Visual Appeal**: Use diagrams generously and consistently
- **Practicality**: Include actionable information and real examples
- **Accessibility**: Semantic HTML, proper headings, alt text, ARIA labels
### Phase 4: Refinement
**4.1 Validate Content**
- Verify all code examples are accurate
- Ensure diagrams correctly represent relationships
- Check that explanations are clear and jargon is explained
- Confirm all CDN links are valid and use specific versions
**4.2 Test Rendering**
- HTML structure is valid
- All scripts load correctly
- Mermaid diagrams render properly
- Syntax highlighting works
- Responsive design functions across screen sizes
- Print/PDF export is clean
**4.3 Polish**
- Consistent styling throughout
- Proper heading hierarchy
- Smooth navigation
- Professional appearance
- Loading states for heavy content
## CDN Dependencies Reference
**Always use specific version numbers for reliability:**
```html
<!-- Mermaid.js -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.0/dist/mermaid.min.js"></script>
<!-- Highlight.js (syntax highlighting) -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<!-- Reveal.js (for slideshows) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js@5.0.4/dist/reveal.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js@5.0.4/dist/theme/white.css">
<script src="https://cdn.jsdelivr.net/npm/reveal.js@5.0.4/dist/reveal.js"></script>
<!-- Font Awesome (icons) -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
<!-- Google Fonts (typography) -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
```
## Mermaid Diagram Best Practices
**Use appropriate diagram types:**
```mermaid
%% Entity-Relationship Diagram
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER {
string name
string email
}
%% Class Diagram
classDiagram
class Animal {
+String name
+makeSound()
}
class Dog {
+bark()
}
Animal <|-- Dog
%% Sequence Diagram
sequenceDiagram
participant User
participant API
participant Database
User->>API: Request data
API->>Database: Query
Database-->>API: Results
API-->>User: Response
%% Flowchart
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
%% State Diagram
stateDiagram-v2
[*] --> Draft
Draft --> Review
Review --> Published
Review --> Draft
Published --> [*]
%% Architecture Diagram
graph TB
subgraph "Frontend"
A[React App]
end
subgraph "Backend"
B[API Gateway]
C[Service 1]
D[Service 2]
end
subgraph "Data"
E[(Database)]
end
A --> B
B --> C
B --> D
C --> E
D --> E
```
**Apply pastel styling:**
```javascript
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#FFE6E6',
primaryTextColor: '#333',
primaryBorderColor: '#999',
lineColor: '#666',
secondaryColor: '#E6F3FF',
tertiaryColor: '#E6FFE6',
quaternaryColor: '#FFF4E6',
quinaryColor: '#F0E6FF',
fontFamily: 'Inter, sans-serif',
fontSize: '14px'
}
});
```
## Important Constraints
**MUST DO:**
- ✅ Save all HTML files to `/tmp` directory with timestamped filenames
- ✅ Open the file in browser using `xdg-open` immediately after creation
- ✅ Create self-contained HTML files (all dependencies via CDN)
- ✅ Use specific version numbers for all CDN resources
- ✅ Verify information against actual sources (code, docs, research)
- ✅ Use light pastel colors for all Mermaid diagrams
- ✅ Include proper semantic HTML and accessibility features
- ✅ Make responsive designs that work on mobile and desktop
- ✅ Add print styles for clean PDF export
- ✅ Initialize all JavaScript libraries properly
**MUST NOT DO:**
- ❌ Create markdown files (only HTML)
- ❌ Rely on potentially outdated documentation when code is available
- ❌ Include placeholder content or "TODO" items
- ❌ Use dark colors in Mermaid diagrams
- ❌ Require build tools, servers, or external files
- ❌ Make assumptions - research or ask for clarification
- ❌ Use relative file paths (all dependencies must be CDN or embedded)
## File Naming and Location
**All files MUST be created in `/tmp` directory with timestamps.**
Format: `/tmp/{descriptive-name}-{timestamp}.html`
Examples:
- `/tmp/architecture-overview-20250104-143022.html` - System architecture long-page
- `/tmp/onboarding-tutorial-20250104-143155.html` - Onboarding guide
- `/tmp/api-documentation-dashboard-20250104-150330.html` - API docs in dashboard format
- `/tmp/deployment-process-slideshow-20250104-151200.html` - Deployment presentation
- `/tmp/database-schema-infographic-20250104-152045.html` - Database ER infographic
- `/tmp/react-hooks-guide-20250104-160000.html` - React hooks tutorial
**After creating the file, ALWAYS run:**
```bash
xdg-open /tmp/{filename}.html
```
## Examples
### Example 1: Technical Onboarding from Codebase
**User request:**
```
Create an onboarding guide for our multi-tenant Rails system
```
**You would:**
1. **Research Phase:**
- Search for tenant-related models: `app/models/*tenant*.rb`
- Read tenant migration files in `db/migrate/`
- Examine `config/application.rb` for tenant config
- Review `app/controllers/concerns/tenant_scoped.rb` or similar
- Check test files for usage examples
2. **Content Planning:**
- Format: Long-page (comprehensive reference)
- Structure: Overview → Architecture → Database → Code Examples → Workflows
- Diagrams: ER diagram of tenant relationships, sequence diagram of tenant resolution, architecture diagram
3. **Generate HTML:**
- Create `/tmp/multi-tenancy-onboarding-20250104-143022.html`
- Include introduction explaining why multi-tenancy
- Add Mermaid ER diagram showing tenant tables
- Show code examples from actual models
- Include sequence diagram of request flow with tenant scoping
- Add practical exercises for new developers
- Open in browser: `xdg-open /tmp/multi-tenancy-onboarding-20250104-143022.html`
4. **Validate:**
- Verify all code examples are from actual codebase
- Test that diagrams accurately represent schema
- Ensure explanations are clear for newcomers
### Example 2: Library Documentation Visualization
**User request:**
```
Create a presentation about React hooks
```
**You would:**
1. **Research Phase:**
- Use `mcp__context7__resolve-library-id` with "react"
- Use `mcp__context7__get-library-docs` to fetch React hooks documentation
- Focus on: useState, useEffect, useContext, useMemo, useCallback
- Extract code examples and best practices
2. **Content Planning:**
- Format: Slideshow (step-by-step learning)
- Structure: Intro slide → Each hook gets 2-3 slides → Best practices → Q&A
- Diagrams: Component lifecycle flowchart, state flow diagrams
3. **Generate HTML:**
- Create `/tmp/react-hooks-presentation-20250104-150000.html` with Reveal.js
- Slide 1: Title and overview
- Slides 2-4: useState with examples and diagram
- Slides 5-7: useEffect with lifecycle diagram
- Continue for other hooks
- Final slides: Patterns and anti-patterns
- Use syntax highlighting for all code examples
- Open in browser: `xdg-open /tmp/react-hooks-presentation-20250104-150000.html`
4. **Validate:**
- Verify code examples match current React documentation
- Test slide transitions work smoothly
- Ensure diagrams clarify concepts
### Example 3: Business Process Visualization
**User request:**
```
Visualize our customer onboarding process as an infographic
```
**You would:**
1. **Research Phase:**
- Ask user to describe the process steps
- Identify key stakeholders and touchpoints
- Clarify success criteria and common issues
2. **Content Planning:**
- Format: Infographic (visual-first)
- Structure: Vertical flow with large diagrams
- Diagrams: Swimlane diagram showing roles, flowchart of process steps, state diagram
3. **Generate HTML:**
- Create `/tmp/customer-onboarding-infographic-20250104-152000.html`
- Minimal navigation (infographics are meant to scroll)
- Large, clear Mermaid swimlane diagram
- Icons for each step (Font Awesome)
- Color-coded stages using pastel colors
- Brief text annotations
- Responsive design for viewing on tablets
- Open in browser: `xdg-open /tmp/customer-onboarding-infographic-20250104-152000.html`
4. **Validate:**
- Verify process accuracy with user
- Ensure visual flow is clear and logical
- Test on different screen sizes
### Example 4: API Documentation Dashboard
**User request:**
```
Create interactive documentation for our REST API endpoints
```
**You would:**
1. **Research Phase:**
- Read route files (`config/routes.rb` or `app/routes/`)
- Examine controller actions and parameters
- Check API serializers for response formats
- Review tests for example requests/responses
- Look for OpenAPI/Swagger specs if available
2. **Content Planning:**
- Format: Dashboard (tabbed by resource)
- Structure: Tab per resource → Endpoints → Examples → Schema
- Diagrams: Architecture diagram, sequence diagrams for complex flows
3. **Generate HTML:**
- Create `/tmp/api-documentation-dashboard-20250104-160000.html`
- Tabbed interface with one tab per resource (Users, Orders, Products)
- Each tab contains: overview, endpoints table, request/response examples
- Syntax-highlighted JSON examples
- Mermaid sequence diagrams for authentication flow
- Copy-to-clipboard buttons for code examples
- Open in browser: `xdg-open /tmp/api-documentation-dashboard-20250104-160000.html`
4. **Validate:**
- Verify all endpoints match actual routes
- Test all tabs and navigation work
- Ensure examples are runnable
## Tips for Success
**Research Phase:**
- Don't skip research - accurate content is paramount
- Use the right tool: codebase (Grep/Read), libraries (Context7), concepts (WebSearch)
- When analyzing code, trace through actual execution paths
- Verify information from multiple angles
**Content Design:**
- Start with a clear outline before generating HTML
- Use progressive disclosure - don't overwhelm with everything at once
- Plan diagram placement for maximum pedagogical value
- Consider your audience's familiarity with the topic
**Visual Design:**
- Maintain consistent spacing and typography
- Use white space effectively
- Limit color palette for professional appearance
- Ensure sufficient contrast for readability
- Test on different screen sizes
**Diagrams:**
- Every diagram should clarify, not complicate
- Label all components clearly
- Use consistent notation within a document
- Place diagrams near related text
- Include diagram captions/titles
**Code Examples:**
- Use real, tested code when possible
- Syntax highlight everything
- Keep examples focused and minimal
- Include comments for clarity
- Show both good and bad patterns when teaching
**Polish:**
- Proofread all text for clarity and correctness
- Test all interactive features
- Validate HTML structure
- Check print/PDF output
- Verify all CDN resources load
You are creating materials that help people understand and master complex topics. Quality and accuracy are your top priorities. Take the time to research thoroughly, plan carefully, and execute beautifully.

116
skills/html-visualization/examples/README.md Normal file
View File

@@ -0,0 +1,116 @@
# HTML Visualization Skill - Examples
This directory contains example visualizations created with the html-visualization skill.
## Example Requests
Here are some ways to trigger this skill:
### 1. Technical Documentation from Codebase
```
Create an HTML onboarding guide for our multi-tenant Rails system
```
This will:
- Analyze your codebase for tenant-related code
- Create ER diagrams of database relationships
- Include sequence diagrams of request flow
- Provide code examples from actual implementation
- Use long-page format for comprehensive reference
### 2. Library/Framework Tutorial
```
Create a slideshow presentation about React hooks
```
This will:
- Fetch latest React documentation via Context7 MCP
- Create slides for each hook (useState, useEffect, etc.)
- Include code examples with syntax highlighting
- Add lifecycle diagrams
- Use Reveal.js for presentation format
### 3. API Documentation
```
Create interactive API documentation for our REST endpoints
```
This will:
- Read routes and controllers from codebase
- Create tabbed dashboard interface
- Include request/response examples
- Add authentication flow diagrams
- Provide copy-to-clipboard for code snippets
### 4. Process Visualization
```
Visualize our customer onboarding process as an infographic
```
This will:
- Work from your description of the process
- Create flowcharts and swimlane diagrams
- Use vertical scroll format with large visuals
- Include minimal text, maximum visual impact
- Apply pastel color scheme throughout
### 5. Architecture Overview
```
Create an architecture visualization for our microservices system
```
This will:
- Analyze your codebase structure
- Create architecture diagrams showing services
- Include sequence diagrams for key flows
- Show component relationships
- Use dashboard or long-page format
## Tips for Best Results
1. **Be specific about format**: Mention "slideshow", "dashboard", "long-page", or "infographic" if you have a preference
2. **Provide context**: If the skill should analyze code, make sure your request mentions the specific area (e.g., "our authentication system", "payment processing")
3. **Mention diagrams**: If you want specific types of diagrams, ask for them (e.g., "include an ER diagram", "show the sequence flow")
4. **Specify audience**: Mention if it's for onboarding, documentation, presentation, or reference
## Output
The skill will create a self-contained HTML file that:
- **Saved to `/tmp` directory** with a timestamped filename (e.g., `/tmp/api-docs-20250104-143022.html`)
- **Automatically opens in your default browser** using `xdg-open`
- Works offline (all dependencies via CDN)
- Includes Mermaid diagrams with pastel colors
- Has syntax-highlighted code examples
- Is responsive and mobile-friendly
- Can be printed or exported to PDF
- Requires no build process - just open in browser
### File Location
All generated HTML files are saved to `/tmp` with timestamps:
- Format: `/tmp/{descriptive-name}-{timestamp}.html`
- Example: `/tmp/multi-tenancy-onboarding-20250104-143022.html`
The files remain available in `/tmp` until system restart or cleanup. You can:
- Reopen them anytime: `xdg-open /tmp/{filename}.html`
- List recent files: `ls -lt /tmp/*.html | head`
- Move to a permanent location: `mv /tmp/{filename}.html ~/Documents/`
## Customization
After the HTML is generated, you can:
- Edit content directly in the HTML file
- Adjust colors in the CSS section
- Modify Mermaid diagrams
- Add or remove sections
- Change the layout and styling
All templates are in the `templates/` directory for reference.

688
skills/html-visualization/templates/dashboard-template.html Normal file
View File

@@ -0,0 +1,688 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Topic Name - Dashboard</title>
<!-- Mermaid.js -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.0/dist/mermaid.min.js"></script>
<!-- Syntax highlighting -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<!-- Google Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<!-- Font Awesome -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
line-height: 1.6;
color: #333;
background: #f8f9fa;
}
/* Header */
header {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 2rem;
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}
header h1 {
font-size: 2rem;
margin-bottom: 0.5rem;
}
header p {
opacity: 0.9;
}
/* Container */
.container {
max-width: 1400px;
margin: 0 auto;
padding: 2rem;
}
/* Tabs */
.tabs {
display: flex;
gap: 0.5rem;
margin-bottom: 2rem;
flex-wrap: wrap;
background: white;
padding: 1rem;
border-radius: 8px;
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}
.tab {
padding: 0.75rem 1.5rem;
background: transparent;
border: none;
border-radius: 6px;
cursor: pointer;
font-size: 0.95rem;
font-weight: 500;
color: #555;
transition: all 0.2s;
display: flex;
align-items: center;
gap: 0.5rem;
}
.tab:hover {
background: #f0f0f0;
color: #667eea;
}
.tab.active {
background: #667eea;
color: white;
}
.tab i {
font-size: 1rem;
}
/* Tab content */
.tab-content {
display: none;
background: white;
padding: 2rem;
border-radius: 8px;
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
animation: fadeIn 0.3s;
}
.tab-content.active {
display: block;
}
@keyframes fadeIn {
from { opacity: 0; transform: translateY(10px); }
to { opacity: 1; transform: translateY(0); }
}
/* Typography */
h2 {
font-size: 1.8rem;
margin-bottom: 1rem;
color: #667eea;
padding-bottom: 0.5rem;
border-bottom: 2px solid #e0e0e0;
}
h3 {
font-size: 1.4rem;
margin: 2rem 0 1rem;
color: #444;
}
h4 {
font-size: 1.1rem;
margin: 1.5rem 0 0.75rem;
color: #555;
}
p {
margin-bottom: 1rem;
}
ul, ol {
margin: 1rem 0 1rem 2rem;
}
li {
margin-bottom: 0.5rem;
}
/* Code blocks */
pre {
background: #f6f8fa;
border: 1px solid #e1e4e8;
border-radius: 6px;
padding: 1rem;
overflow-x: auto;
margin: 1rem 0;
position: relative;
}
code {
background: #f6f8fa;
padding: 0.2rem 0.4rem;
border-radius: 3px;
font-family: 'Monaco', 'Courier New', monospace;
font-size: 0.9em;
}
pre code {
background: none;
padding: 0;
}
/* Copy button for code */
.copy-btn {
position: absolute;
top: 0.5rem;
right: 0.5rem;
padding: 0.25rem 0.5rem;
background: #667eea;
color: white;
border: none;
border-radius: 4px;
cursor: pointer;
font-size: 0.75rem;
opacity: 0;
transition: opacity 0.2s;
}
pre:hover .copy-btn {
opacity: 1;
}
.copy-btn:hover {
background: #5568d3;
}
/* Mermaid diagrams */
.mermaid {
background: #fafafa;
border: 1px solid #e0e0e0;
border-radius: 8px;
padding: 2rem;
margin: 1.5rem 0;
text-align: center;
}
/* Info boxes */
.info-box {
background: #e6f3ff;
border-left: 4px solid #667eea;
padding: 1rem 1.5rem;
margin: 1.5rem 0;
border-radius: 4px;
}
.info-box.warning {
background: #fff4e6;
border-left-color: #ff9800;
}
.info-box.tip {
background: #e6ffe6;
border-left-color: #4caf50;
}
.info-box.error {
background: #ffe6e6;
border-left-color: #f44336;
}
.info-box h4 {
margin-top: 0;
}
/* Tables */
table {
width: 100%;
border-collapse: collapse;
margin: 1.5rem 0;
}
th, td {
padding: 0.75rem;
text-align: left;
border-bottom: 1px solid #e0e0e0;
}
th {
background: #f6f8fa;
font-weight: 600;
color: #555;
}
tr:hover {
background: #f9f9f9;
}
/* Cards */
.card-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 1.5rem;
margin: 1.5rem 0;
}
.card {
background: #f8f9fa;
border: 1px solid #e0e0e0;
border-radius: 8px;
padding: 1.5rem;
transition: all 0.2s;
}
.card:hover {
box-shadow: 0 4px 12px rgba(0,0,0,0.1);
transform: translateY(-2px);
}
.card h4 {
margin-top: 0;
color: #667eea;
}
/* Endpoint display */
.endpoint {
background: #f8f9fa;
border: 1px solid #e0e0e0;
border-radius: 8px;
padding: 1.5rem;
margin: 1.5rem 0;
}
.endpoint-header {
display: flex;
align-items: center;
gap: 1rem;
margin-bottom: 1rem;
}
.method {
padding: 0.25rem 0.75rem;
border-radius: 4px;
font-weight: 600;
font-size: 0.85rem;
}
.method.get { background: #e6ffe6; color: #2e7d32; }
.method.post { background: #e6f3ff; color: #1565c0; }
.method.put { background: #fff4e6; color: #ef6c00; }
.method.delete { background: #ffe6e6; color: #c62828; }
.endpoint-path {
font-family: 'Monaco', monospace;
font-size: 1.1rem;
font-weight: 500;
}
/* Responsive */
@media (max-width: 768px) {
.container {
padding: 1rem;
}
.tabs {
flex-direction: column;
}
.tab {
width: 100%;
}
.tab-content {
padding: 1.5rem;
}
header h1 {
font-size: 1.5rem;
}
}
/* Print styles */
@media print {
body {
background: white;
}
header {
background: none;
color: #333;
}
.tabs {
display: none;
}
.tab-content {
display: block !important;
box-shadow: none;
page-break-inside: avoid;
margin-bottom: 2rem;
}
.copy-btn {
display: none;
}
}
</style>
</head>
<body>
<header>
<h1>API Documentation</h1>
<p>Complete reference for the REST API</p>
</header>
<div class="container">
<!-- Tabs -->
<div class="tabs">
<button class="tab active" data-tab="overview">
<i class="fas fa-home"></i> Overview
</button>
<button class="tab" data-tab="users">
<i class="fas fa-users"></i> Users
</button>
<button class="tab" data-tab="products">
<i class="fas fa-box"></i> Products
</button>
<button class="tab" data-tab="orders">
<i class="fas fa-shopping-cart"></i> Orders
</button>
<button class="tab" data-tab="auth">
<i class="fas fa-lock"></i> Authentication
</button>
</div>
<!-- Overview Tab -->
<div class="tab-content active" id="overview">
<h2>API Overview</h2>
<p>
Welcome to the API documentation. This API provides comprehensive access to all features.
</p>
<h3>Architecture</h3>
<div class="mermaid">
graph LR
A[Client] -->|HTTPS| B[API Gateway]
B --> C[Auth Service]
B --> D[User Service]
B --> E[Product Service]
B --> F[Order Service]
D --> G[(Database)]
E --> G
F --> G
style A fill:#FFE6E6
style B fill:#E6F3FF
style C fill:#E6FFE6
style D fill:#E6FFE6
style E fill:#E6FFE6
style F fill:#E6FFE6
style G fill:#FFF4E6
</div>
<h3>Quick Start</h3>
<div class="card-grid">
<div class="card">
<h4>1. Get API Key</h4>
<p>Sign up and generate your API key from the dashboard.</p>
</div>
<div class="card">
<h4>2. Make Request</h4>
<p>Include your API key in the Authorization header.</p>
</div>
<div class="card">
<h4>3. Handle Response</h4>
<p>Parse JSON responses and handle errors appropriately.</p>
</div>
</div>
<h3>Base URL</h3>
<pre><code>https://api.example.com/v1</code></pre>
<div class="info-box">
<h4>Rate Limits</h4>
<p>All endpoints are rate-limited to 100 requests per minute per API key.</p>
</div>
</div>
<!-- Users Tab -->
<div class="tab-content" id="users">
<h2>Users API</h2>
<p>Manage user accounts and profiles.</p>
<!-- List Users -->
<div class="endpoint">
<div class="endpoint-header">
<span class="method get">GET</span>
<span class="endpoint-path">/users</span>
</div>
<p><strong>Description:</strong> Retrieve a list of users.</p>
<h4>Query Parameters</h4>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>page</code></td>
<td>integer</td>
<td>No</td>
<td>Page number (default: 1)</td>
</tr>
<tr>
<td><code>limit</code></td>
<td>integer</td>
<td>No</td>
<td>Items per page (default: 20)</td>
</tr>
</tbody>
</table>
<h4>Example Request</h4>
<pre><code class="language-bash">curl -X GET "https://api.example.com/v1/users?page=1&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"</code><button class="copy-btn" onclick="copyCode(this)">Copy</button></pre>
<h4>Example Response</h4>
<pre><code class="language-json">{
"data": [
{
"id": 1,
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-01T00:00:00Z"
}
],
"meta": {
"page": 1,
"total": 100
}
}</code><button class="copy-btn" onclick="copyCode(this)">Copy</button></pre>
</div>
<!-- Create User -->
<div class="endpoint">
<div class="endpoint-header">
<span class="method post">POST</span>
<span class="endpoint-path">/users</span>
</div>
<p><strong>Description:</strong> Create a new user.</p>
<h4>Request Body</h4>
<pre><code class="language-json">{
"name": "Jane Doe",
"email": "jane@example.com",
"password": "securepassword123"
}</code><button class="copy-btn" onclick="copyCode(this)">Copy</button></pre>
<div class="info-box tip">
<h4>Validation Rules</h4>
<ul>
<li>Email must be unique</li>
<li>Password must be at least 8 characters</li>
<li>Name is required</li>
</ul>
</div>
</div>
</div>
<!-- Products Tab -->
<div class="tab-content" id="products">
<h2>Products API</h2>
<p>Manage product catalog.</p>
<h3>Product Schema</h3>
<div class="mermaid">
erDiagram
PRODUCT {
int id PK
string name
string description
decimal price
int category_id FK
datetime created_at
}
CATEGORY {
int id PK
string name
}
PRODUCT }o--|| CATEGORY : belongs_to
</div>
<div class="endpoint">
<div class="endpoint-header">
<span class="method get">GET</span>
<span class="endpoint-path">/products</span>
</div>
<p><strong>Description:</strong> List all products with filtering.</p>
</div>
</div>
<!-- Orders Tab -->
<div class="tab-content" id="orders">
<h2>Orders API</h2>
<p>Process and track orders.</p>
<h3>Order Lifecycle</h3>
<div class="mermaid">
stateDiagram-v2
[*] --> Pending
Pending --> Processing : payment confirmed
Processing --> Shipped : items dispatched
Shipped --> Delivered : received
Pending --> Cancelled : cancelled
Processing --> Cancelled : cancelled
Delivered --> [*]
Cancelled --> [*]
</div>
</div>
<!-- Auth Tab -->
<div class="tab-content" id="auth">
<h2>Authentication</h2>
<p>Secure your API requests with token-based authentication.</p>
<h3>Authentication Flow</h3>
<div class="mermaid">
sequenceDiagram
participant Client
participant API
participant Auth
Client->>API: POST /auth/login
API->>Auth: Validate credentials
Auth-->>API: Generate token
API-->>Client: Return JWT token
Client->>API: Request with token
API->>Auth: Verify token
Auth-->>API: Token valid
API-->>Client: Protected resource
</div>
<h3>Obtaining a Token</h3>
<pre><code class="language-bash">curl -X POST "https://api.example.com/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "yourpassword"
}'</code><button class="copy-btn" onclick="copyCode(this)">Copy</button></pre>
<div class="info-box warning">
<h4>Security Best Practices</h4>
<ul>
<li>Never share your API key</li>
<li>Use HTTPS for all requests</li>
<li>Rotate tokens regularly</li>
<li>Store tokens securely</li>
</ul>
</div>
</div>
</div>
<script>
// Initialize Mermaid with pastel theme
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#FFE6E6',
primaryTextColor: '#333',
primaryBorderColor: '#999',
lineColor: '#666',
secondaryColor: '#E6F3FF',
tertiaryColor: '#E6FFE6',
quaternaryColor: '#FFF4E6',
quinaryColor: '#F0E6FF',
fontFamily: 'Inter, sans-serif'
}
});
// Initialize syntax highlighting
hljs.highlightAll();
// Tab switching
const tabs = document.querySelectorAll('.tab');
const tabContents = document.querySelectorAll('.tab-content');
tabs.forEach(tab => {
tab.addEventListener('click', () => {
const targetTab = tab.dataset.tab;
// Remove active class from all tabs and contents
tabs.forEach(t => t.classList.remove('active'));
tabContents.forEach(c => c.classList.remove('active'));
// Add active class to clicked tab and corresponding content
tab.classList.add('active');
document.getElementById(targetTab).classList.add('active');
// Re-render Mermaid diagrams
mermaid.init(undefined, document.querySelectorAll('.mermaid'));
});
});
// Copy to clipboard
function copyCode(button) {
const pre = button.parentElement;
const code = pre.querySelector('code');
const text = code.textContent;
navigator.clipboard.writeText(text).then(() => {
button.textContent = 'Copied!';
setTimeout(() => {
button.textContent = 'Copy';
}, 2000);
});
}
</script>
</body>
</html>

655
skills/html-visualization/templates/infographic-template.html Normal file
View File

@@ -0,0 +1,655 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Topic Name - Infographic</title>
<!-- Mermaid.js -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.0/dist/mermaid.min.js"></script>
<!-- Google Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&display=swap" rel="stylesheet">
<!-- Font Awesome -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
line-height: 1.6;
color: #333;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
padding: 2rem 0;
}
.infographic {
max-width: 900px;
margin: 0 auto;
background: white;
border-radius: 16px;
overflow: hidden;
box-shadow: 0 20px 60px rgba(0,0,0,0.3);
}
/* Header */
.header {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 4rem 2rem;
text-align: center;
position: relative;
overflow: hidden;
}
.header::before {
content: '';
position: absolute;
top: 0;
left: 0;
right: 0;
bottom: 0;
background: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><circle cx="50" cy="50" r="40" fill="white" opacity="0.05"/></svg>');
background-size: 100px;
}
.header h1 {
font-size: 3rem;
font-weight: 900;
margin-bottom: 0.5rem;
position: relative;
z-index: 1;
}
.header p {
font-size: 1.3rem;
opacity: 0.95;
position: relative;
z-index: 1;
}
/* Content sections */
.section {
padding: 3rem 2rem;
position: relative;
}
.section:nth-child(even) {
background: #f8f9fa;
}
.section-number {
position: absolute;
top: 2rem;
left: 2rem;
font-size: 4rem;
font-weight: 900;
color: #667eea;
opacity: 0.1;
}
.section h2 {
font-size: 2rem;
margin-bottom: 1.5rem;
color: #667eea;
font-weight: 700;
text-align: center;
}
.section h3 {
font-size: 1.5rem;
margin: 2rem 0 1rem;
color: #444;
font-weight: 600;
}
.section p {
font-size: 1.1rem;
margin-bottom: 1rem;
text-align: center;
max-width: 700px;
margin-left: auto;
margin-right: auto;
}
/* Icon grid */
.icon-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 2rem;
margin: 2rem 0;
}
.icon-item {
text-align: center;
padding: 1.5rem;
border-radius: 12px;
transition: transform 0.3s;
}
.icon-item:hover {
transform: translateY(-5px);
}
.icon-item i {
font-size: 3rem;
margin-bottom: 1rem;
display: block;
}
.icon-item h4 {
font-size: 1.2rem;
margin-bottom: 0.5rem;
font-weight: 600;
}
.icon-item p {
font-size: 0.95rem;
color: #666;
}
/* Color variants */
.icon-item:nth-child(4n+1) { background: #FFE6E6; }
.icon-item:nth-child(4n+1) i { color: #e53935; }
.icon-item:nth-child(4n+2) { background: #E6F3FF; }
.icon-item:nth-child(4n+2) i { color: #1e88e5; }
.icon-item:nth-child(4n+3) { background: #E6FFE6; }
.icon-item:nth-child(4n+3) i { color: #43a047; }
.icon-item:nth-child(4n+4) { background: #FFF4E6; }
.icon-item:nth-child(4n+4) i { color: #fb8c00; }
/* Stats */
.stats {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
gap: 2rem;
margin: 2rem 0;
}
.stat {
text-align: center;
padding: 2rem 1rem;
background: white;
border-radius: 12px;
box-shadow: 0 4px 12px rgba(0,0,0,0.1);
}
.stat-number {
font-size: 3rem;
font-weight: 900;
color: #667eea;
display: block;
margin-bottom: 0.5rem;
}
.stat-label {
font-size: 0.95rem;
color: #666;
text-transform: uppercase;
letter-spacing: 0.05em;
}
/* Timeline */
.timeline {
position: relative;
padding: 2rem 0;
margin: 2rem 0;
}
.timeline::before {
content: '';
position: absolute;
left: 50%;
top: 0;
bottom: 0;
width: 3px;
background: linear-gradient(180deg, #667eea 0%, #764ba2 100%);
transform: translateX(-50%);
}
.timeline-item {
position: relative;
margin-bottom: 3rem;
display: flex;
align-items: center;
}
.timeline-item:nth-child(odd) {
flex-direction: row;
}
.timeline-item:nth-child(even) {
flex-direction: row-reverse;
}
.timeline-content {
width: 45%;
padding: 1.5rem;
background: white;
border-radius: 12px;
box-shadow: 0 4px 12px rgba(0,0,0,0.1);
}
.timeline-dot {
position: absolute;
left: 50%;
width: 20px;
height: 20px;
background: #667eea;
border: 4px solid white;
border-radius: 50%;
transform: translateX(-50%);
box-shadow: 0 0 0 4px rgba(102, 126, 234, 0.2);
}
.timeline-content h4 {
font-size: 1.3rem;
margin-bottom: 0.5rem;
color: #667eea;
}
.timeline-content p {
text-align: left;
font-size: 0.95rem;
}
/* Mermaid diagrams */
.mermaid {
background: #fafafa;
border-radius: 12px;
padding: 2rem;
margin: 2rem 0;
}
/* Large diagram section */
.diagram-section {
padding: 3rem 1rem;
background: #fafafa;
}
/* CTA Section */
.cta-section {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 4rem 2rem;
text-align: center;
}
.cta-section h2 {
color: white;
font-size: 2.5rem;
margin-bottom: 1rem;
}
.cta-section p {
color: white;
font-size: 1.2rem;
margin-bottom: 2rem;
opacity: 0.95;
}
.cta-button {
display: inline-block;
padding: 1rem 2rem;
background: white;
color: #667eea;
text-decoration: none;
border-radius: 8px;
font-weight: 600;
font-size: 1.1rem;
transition: transform 0.2s;
}
.cta-button:hover {
transform: scale(1.05);
}
/* Process flow */
.process-flow {
display: flex;
justify-content: space-between;
align-items: center;
margin: 2rem 0;
gap: 1rem;
}
.process-step {
flex: 1;
text-align: center;
padding: 2rem 1rem;
background: white;
border-radius: 12px;
box-shadow: 0 4px 12px rgba(0,0,0,0.1);
position: relative;
}
.process-step::after {
content: '→';
position: absolute;
right: -1.5rem;
top: 50%;
transform: translateY(-50%);
font-size: 2rem;
color: #667eea;
}
.process-step:last-child::after {
display: none;
}
.process-step i {
font-size: 2.5rem;
color: #667eea;
margin-bottom: 1rem;
}
.process-step h4 {
font-size: 1.1rem;
margin-bottom: 0.5rem;
}
.process-step p {
font-size: 0.9rem;
color: #666;
}
/* Responsive */
@media (max-width: 768px) {
body {
padding: 0;
}
.infographic {
border-radius: 0;
}
.header h1 {
font-size: 2rem;
}
.header p {
font-size: 1.1rem;
}
.section {
padding: 2rem 1rem;
}
.timeline::before {
left: 20px;
}
.timeline-item {
flex-direction: row !important;
padding-left: 50px;
}
.timeline-content {
width: 100%;
}
.timeline-dot {
left: 20px;
}
.process-flow {
flex-direction: column;
}
.process-step::after {
content: '↓';
right: auto;
top: auto;
bottom: -1.5rem;
left: 50%;
transform: translateX(-50%);
}
}
/* Print styles */
@media print {
body {
background: white;
padding: 0;
}
.infographic {
box-shadow: none;
}
.section {
page-break-inside: avoid;
}
}
</style>
</head>
<body>
<div class="infographic">
<!-- Header -->
<div class="header">
<h1>The Complete Guide</h1>
<p>Understanding [Topic] in 5 Minutes</p>
</div>
<!-- Introduction Section -->
<div class="section">
<div class="section-number">01</div>
<h2>What is it?</h2>
<p>
A brief, compelling introduction to the topic. Explain in simple terms what it is and why it matters.
</p>
<div class="stats">
<div class="stat">
<span class="stat-number">85%</span>
<span class="stat-label">Improvement</span>
</div>
<div class="stat">
<span class="stat-number">10x</span>
<span class="stat-label">Faster</span>
</div>
<div class="stat">
<span class="stat-number">50K+</span>
<span class="stat-label">Users</span>
</div>
<div class="stat">
<span class="stat-number">99.9%</span>
<span class="stat-label">Uptime</span>
</div>
</div>
</div>
<!-- Key Features Section -->
<div class="section">
<div class="section-number">02</div>
<h2>Key Features</h2>
<p>The main capabilities and benefits that make this powerful.</p>
<div class="icon-grid">
<div class="icon-item">
<i class="fas fa-rocket"></i>
<h4>Fast Performance</h4>
<p>Lightning-fast processing with optimized algorithms</p>
</div>
<div class="icon-item">
<i class="fas fa-shield-alt"></i>
<h4>Secure</h4>
<p>Enterprise-grade security built in from the ground up</p>
</div>
<div class="icon-item">
<i class="fas fa-puzzle-piece"></i>
<h4>Flexible</h4>
<p>Adapts to your needs with extensive customization</p>
</div>
<div class="icon-item">
<i class="fas fa-chart-line"></i>
<h4>Scalable</h4>
<p>Grows with your business from startup to enterprise</p>
</div>
</div>
</div>
<!-- Architecture Diagram -->
<div class="section diagram-section">
<div class="section-number">03</div>
<h2>How It Works</h2>
<p>Visual overview of the architecture and data flow.</p>
<div class="mermaid">
graph TB
subgraph "User Interface"
A[Web App]
B[Mobile App]
C[Desktop App]
end
subgraph "API Layer"
D[API Gateway]
E[Load Balancer]
end
subgraph "Services"
F[Auth Service]
G[Business Logic]
H[Data Processing]
end
subgraph "Data Storage"
I[(Primary DB)]
J[(Cache)]
K[(File Storage)]
end
A --> D
B --> D
C --> D
D --> E
E --> F
E --> G
E --> H
F --> I
G --> I
G --> J
H --> K
style A fill:#FFE6E6
style B fill:#FFE6E6
style C fill:#FFE6E6
style D fill:#E6F3FF
style E fill:#E6F3FF
style F fill:#E6FFE6
style G fill:#E6FFE6
style H fill:#E6FFE6
style I fill:#FFF4E6
style J fill:#FFF4E6
style K fill:#FFF4E6
</div>
</div>
<!-- Process Flow -->
<div class="section">
<div class="section-number">04</div>
<h2>The Process</h2>
<p>Step-by-step workflow from start to finish.</p>
<div class="process-flow">
<div class="process-step">
<i class="fas fa-sign-in-alt"></i>
<h4>Step 1</h4>
<p>User initiates the process</p>
</div>
<div class="process-step">
<i class="fas fa-cogs"></i>
<h4>Step 2</h4>
<p>System processes data</p>
</div>
<div class="process-step">
<i class="fas fa-check-circle"></i>
<h4>Step 3</h4>
<p>Results are validated</p>
</div>
<div class="process-step">
<i class="fas fa-paper-plane"></i>
<h4>Step 4</h4>
<p>Output is delivered</p>
</div>
</div>
</div>
<!-- Timeline -->
<div class="section">
<div class="section-number">05</div>
<h2>Evolution Timeline</h2>
<p>How we got here and where we're going.</p>
<div class="timeline">
<div class="timeline-item">
<div class="timeline-content">
<h4>Phase 1: Foundation</h4>
<p>Built the core infrastructure and basic features</p>
</div>
<div class="timeline-dot"></div>
</div>
<div class="timeline-item">
<div class="timeline-content">
<h4>Phase 2: Growth</h4>
<p>Expanded capabilities and user base</p>
</div>
<div class="timeline-dot"></div>
</div>
<div class="timeline-item">
<div class="timeline-content">
<h4>Phase 3: Scale</h4>
<p>Enhanced performance and reliability</p>
</div>
<div class="timeline-dot"></div>
</div>
<div class="timeline-item">
<div class="timeline-content">
<h4>Phase 4: Innovation</h4>
<p>Introducing AI and advanced automation</p>
</div>
<div class="timeline-dot"></div>
</div>
</div>
</div>
<!-- CTA Section -->
<div class="cta-section">
<h2>Ready to Get Started?</h2>
<p>Join thousands of users already benefiting from this solution</p>
<a href="#" class="cta-button">Learn More</a>
</div>
</div>
<script>
// Initialize Mermaid with pastel theme
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#FFE6E6',
primaryTextColor: '#333',
primaryBorderColor: '#999',
lineColor: '#666',
secondaryColor: '#E6F3FF',
tertiaryColor: '#E6FFE6',
quaternaryColor: '#FFF4E6',
quinaryColor: '#F0E6FF',
fontFamily: 'Inter, sans-serif',
fontSize: '16px'
}
});
</script>
</body>
</html>

483
skills/html-visualization/templates/long-page-template.html Normal file
View File

@@ -0,0 +1,483 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Topic Name - Documentation</title>
<!-- Mermaid.js -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.0/dist/mermaid.min.js"></script>
<!-- Syntax highlighting -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<!-- Google Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
line-height: 1.6;
color: #333;
background: #f8f9fa;
}
.container {
max-width: 1200px;
margin: 0 auto;
display: grid;
grid-template-columns: 250px 1fr;
gap: 2rem;
}
/* Header */
header {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 3rem 2rem;
text-align: center;
}
header h1 {
font-size: 2.5rem;
margin-bottom: 0.5rem;
font-weight: 700;
}
header p {
font-size: 1.1rem;
opacity: 0.9;
}
/* Navigation */
nav {
position: sticky;
top: 2rem;
height: fit-content;
background: white;
padding: 1.5rem;
border-radius: 8px;
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}
nav h3 {
margin-bottom: 1rem;
font-size: 0.875rem;
text-transform: uppercase;
color: #667eea;
letter-spacing: 0.05em;
}
nav ul {
list-style: none;
}
nav a {
display: block;
padding: 0.5rem 0.75rem;
color: #555;
text-decoration: none;
border-radius: 4px;
transition: all 0.2s;
font-size: 0.95rem;
}
nav a:hover {
background: #f0f0f0;
color: #667eea;
padding-left: 1rem;
}
nav a.active {
background: #667eea;
color: white;
}
/* Main content */
main {
background: white;
padding: 3rem;
border-radius: 8px;
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
margin: 2rem 0;
}
section {
margin-bottom: 4rem;
scroll-margin-top: 2rem;
}
section:last-child {
margin-bottom: 0;
}
h2 {
font-size: 2rem;
margin-bottom: 1rem;
color: #667eea;
padding-bottom: 0.5rem;
border-bottom: 2px solid #e0e0e0;
}
h3 {
font-size: 1.5rem;
margin: 2rem 0 1rem;
color: #444;
}
h4 {
font-size: 1.2rem;
margin: 1.5rem 0 0.75rem;
color: #555;
}
p {
margin-bottom: 1rem;
}
ul, ol {
margin: 1rem 0 1rem 2rem;
}
li {
margin-bottom: 0.5rem;
}
/* Code blocks */
pre {
background: #f6f8fa;
border: 1px solid #e1e4e8;
border-radius: 6px;
padding: 1rem;
overflow-x: auto;
margin: 1rem 0;
}
code {
background: #f6f8fa;
padding: 0.2rem 0.4rem;
border-radius: 3px;
font-family: 'Monaco', 'Courier New', monospace;
font-size: 0.9em;
}
pre code {
background: none;
padding: 0;
}
/* Mermaid diagrams */
.mermaid {
background: #fafafa;
border: 1px solid #e0e0e0;
border-radius: 8px;
padding: 2rem;
margin: 2rem 0;
text-align: center;
}
/* Info boxes */
.info-box {
background: #e6f3ff;
border-left: 4px solid #667eea;
padding: 1rem 1.5rem;
margin: 1.5rem 0;
border-radius: 4px;
}
.info-box.warning {
background: #fff4e6;
border-left-color: #ff9800;
}
.info-box.tip {
background: #e6ffe6;
border-left-color: #4caf50;
}
.info-box h4 {
margin-top: 0;
}
/* Tables */
table {
width: 100%;
border-collapse: collapse;
margin: 1.5rem 0;
}
th, td {
padding: 0.75rem;
text-align: left;
border-bottom: 1px solid #e0e0e0;
}
th {
background: #f6f8fa;
font-weight: 600;
color: #555;
}
tr:hover {
background: #f9f9f9;
}
/* Responsive */
@media (max-width: 768px) {
.container {
grid-template-columns: 1fr;
}
nav {
position: static;
order: -1;
}
main {
padding: 1.5rem;
}
header h1 {
font-size: 1.8rem;
}
}
/* Print styles */
@media print {
body {
background: white;
}
.container {
display: block;
}
nav {
display: none;
}
main {
box-shadow: none;
padding: 0;
}
section {
page-break-inside: avoid;
}
h2 {
page-break-after: avoid;
}
}
</style>
</head>
<body>
<header>
<h1>Topic Name</h1>
<p>A comprehensive guide for understanding and working with [feature/concept]</p>
</header>
<div class="container">
<nav>
<h3>Contents</h3>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#architecture">Architecture</a></li>
<li><a href="#use-cases">Use Cases</a></li>
<li><a href="#examples">Code Examples</a></li>
<li><a href="#next-steps">Next Steps</a></li>
</ul>
</nav>
<main>
<section id="overview">
<h2>Overview</h2>
<p>
Brief introduction to the topic. Explain what it is, why it matters, and what this document covers.
</p>
<div class="info-box">
<h4>Key Concepts</h4>
<ul>
<li>Concept 1: Brief explanation</li>
<li>Concept 2: Brief explanation</li>
<li>Concept 3: Brief explanation</li>
</ul>
</div>
</section>
<section id="architecture">
<h2>Architecture</h2>
<p>
High-level architecture explanation with visual diagrams.
</p>
<div class="mermaid">
graph TB
subgraph "Frontend Layer"
A[Web Client]
B[Mobile App]
end
subgraph "Application Layer"
C[API Gateway]
D[Service 1]
E[Service 2]
end
subgraph "Data Layer"
F[(Database)]
G[(Cache)]
end
A --> C
B --> C
C --> D
C --> E
D --> F
E --> F
D --> G
style A fill:#FFE6E6
style B fill:#FFE6E6
style C fill:#E6F3FF
style D fill:#E6FFE6
style E fill:#E6FFE6
style F fill:#FFF4E6
style G fill:#FFF4E6
</div>
<h3>Component Relationships</h3>
<p>Detailed explanation of how components interact...</p>
</section>
<section id="use-cases">
<h2>Use Cases</h2>
<h3>Use Case 1: Primary Workflow</h3>
<p>Description of the main use case and workflow.</p>
<div class="mermaid">
sequenceDiagram
participant User
participant Frontend
participant API
participant Database
User->>Frontend: Initiates action
Frontend->>API: POST /api/action
API->>Database: Query data
Database-->>API: Return results
API-->>Frontend: JSON response
Frontend-->>User: Display result
</div>
<h3>Use Case 2: Alternative Scenario</h3>
<p>Another common scenario and how it works...</p>
</section>
<section id="examples">
<h2>Code Examples</h2>
<h3>Basic Example</h3>
<pre><code class="language-javascript">// Example code with syntax highlighting
function example() {
const data = fetchData();
return processData(data);
}
</code></pre>
<div class="info-box tip">
<h4>Best Practice</h4>
<p>Always validate input before processing...</p>
</div>
<h3>Advanced Example</h3>
<pre><code class="language-javascript">// More complex example
class AdvancedFeature {
constructor(config) {
this.config = config;
}
async process() {
// Implementation details
}
}
</code></pre>
</section>
<section id="next-steps">
<h2>Next Steps</h2>
<p>Practical exercises and further learning resources.</p>
<h3>Practice Exercises</h3>
<ol>
<li>Exercise 1: Build a simple implementation</li>
<li>Exercise 2: Add advanced features</li>
<li>Exercise 3: Optimize performance</li>
</ol>
<h3>Further Reading</h3>
<ul>
<li>Documentation link 1</li>
<li>Documentation link 2</li>
<li>Related topics</li>
</ul>
</section>
</main>
</div>
<script>
// Initialize Mermaid with pastel theme
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#FFE6E6',
primaryTextColor: '#333',
primaryBorderColor: '#999',
lineColor: '#666',
secondaryColor: '#E6F3FF',
tertiaryColor: '#E6FFE6',
quaternaryColor: '#FFF4E6',
quinaryColor: '#F0E6FF',
fontFamily: 'Inter, sans-serif'
}
});
// Initialize syntax highlighting
hljs.highlightAll();
// Smooth scroll for navigation links
document.querySelectorAll('nav a').forEach(link => {
link.addEventListener('click', (e) => {
e.preventDefault();
const target = document.querySelector(link.getAttribute('href'));
target.scrollIntoView({ behavior: 'smooth' });
});
});
// Active section highlighting in nav
const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
const id = entry.target.getAttribute('id');
document.querySelectorAll('nav a').forEach(link => {
link.classList.remove('active');
});
document.querySelector(`nav a[href="#${id}"]`)?.classList.add('active');
}
});
}, { threshold: 0.5 });
document.querySelectorAll('section').forEach(section => {
observer.observe(section);
});
</script>
</body>
</html>

366
skills/html-visualization/templates/slideshow-template.html Normal file
View File

@@ -0,0 +1,366 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Topic Name - Presentation</title>
<!-- Reveal.js -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js@5.0.4/dist/reveal.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js@5.0.4/dist/theme/white.css">
<!-- Mermaid.js -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.0/dist/mermaid.min.js"></script>
<!-- Syntax highlighting -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<!-- Google Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<style>
.reveal {
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}
.reveal h1 {
font-weight: 700;
color: #667eea;
}
.reveal h2 {
font-weight: 600;
color: #764ba2;
}
.reveal h3 {
font-weight: 500;
color: #555;
}
.reveal .slides {
text-align: left;
}
.reveal .title-slide {
text-align: center;
}
.reveal code {
background: #f6f8fa;
padding: 0.2rem 0.4rem;
border-radius: 3px;
font-family: 'Monaco', 'Courier New', monospace;
}
.reveal pre {
box-shadow: 0 5px 15px rgba(0,0,0,0.15);
border-radius: 8px;
}
.reveal pre code {
background: #f6f8fa;
padding: 1rem;
max-height: 500px;
}
.reveal .mermaid {
background: #fafafa;
border-radius: 8px;
padding: 1rem;
margin: 1rem 0;
}
.reveal .info-box {
background: #e6f3ff;
border-left: 4px solid #667eea;
padding: 1rem 1.5rem;
margin: 1rem 0;
border-radius: 4px;
}
.reveal .info-box.warning {
background: #fff4e6;
border-left-color: #ff9800;
}
.reveal .info-box.tip {
background: #e6ffe6;
border-left-color: #4caf50;
}
.reveal .two-column {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 2rem;
align-items: center;
}
.reveal ul {
list-style-type: none;
padding-left: 0;
}
.reveal ul li:before {
content: "▸ ";
color: #667eea;
font-weight: bold;
margin-right: 0.5rem;
}
.reveal .footer {
position: absolute;
bottom: 1rem;
left: 1rem;
font-size: 0.6em;
color: #999;
}
/* Progress bar color */
.reveal .progress {
background: rgba(102, 126, 234, 0.2);
height: 3px;
}
.reveal .progress span {
background: #667eea;
}
</style>
</head>
<body>
<div class="reveal">
<div class="slides">
<!-- Slide 1: Title -->
<section class="title-slide">
<h1>Topic Name</h1>
<h3>Subtitle or Brief Description</h3>
<p style="margin-top: 2rem; color: #666;">Presenter Name | Date</p>
</section>
<!-- Slide 2: Overview -->
<section>
<h2>Overview</h2>
<ul>
<li>Key concept 1</li>
<li>Key concept 2</li>
<li>Key concept 3</li>
<li>What you'll learn today</li>
</ul>
</section>
<!-- Slide 3: Architecture -->
<section>
<h2>Architecture Overview</h2>
<div class="mermaid">
graph LR
A[Component A] -->|data| B[Component B]
B -->|process| C[Component C]
C -->|result| D[Component D]
style A fill:#FFE6E6
style B fill:#E6F3FF
style C fill:#E6FFE6
style D fill:#FFF4E6
</div>
<p style="font-size: 0.9em; margin-top: 1rem;">
Brief explanation of the architecture...
</p>
</section>
<!-- Slide 4: Two Column Layout -->
<section>
<h2>Concept Explanation</h2>
<div class="two-column">
<div>
<h3>What it is</h3>
<ul>
<li>Point 1</li>
<li>Point 2</li>
<li>Point 3</li>
</ul>
</div>
<div>
<h3>Why it matters</h3>
<ul>
<li>Benefit 1</li>
<li>Benefit 2</li>
<li>Benefit 3</li>
</ul>
</div>
</div>
</section>
<!-- Slide 5: Code Example -->
<section>
<h2>Code Example</h2>
<pre><code class="language-javascript">// Basic implementation
function example(data) {
// Validate input
if (!data) {
throw new Error('Data required');
}
// Process
const result = data.map(item => {
return transform(item);
});
return result;
}
</code></pre>
<div class="info-box tip" style="font-size: 0.8em;">
<strong>Tip:</strong> Always validate input before processing
</div>
</section>
<!-- Slide 6: Sequence Diagram -->
<section>
<h2>Request Flow</h2>
<div class="mermaid">
sequenceDiagram
participant User
participant Frontend
participant API
participant DB
User->>Frontend: Action
Frontend->>API: Request
API->>DB: Query
DB-->>API: Data
API-->>Frontend: Response
Frontend-->>User: Display
</div>
</section>
<!-- Slide 7: Vertical Slides (nested) -->
<section>
<section>
<h2>Advanced Topics</h2>
<p>Press <strong>↓</strong> to explore subtopics</p>
<ul>
<li>Topic 1</li>
<li>Topic 2</li>
<li>Topic 3</li>
</ul>
</section>
<section>
<h3>Topic 1: Details</h3>
<p>Deep dive into the first topic...</p>
<pre><code class="language-javascript">// Example for topic 1
const topic1 = new Feature();
</code></pre>
</section>
<section>
<h3>Topic 2: Details</h3>
<p>Deep dive into the second topic...</p>
</section>
</section>
<!-- Slide 8: Best Practices -->
<section>
<h2>Best Practices</h2>
<div class="info-box">
<h3 style="margin-top: 0;">✅ Do</h3>
<ul style="font-size: 0.9em;">
<li>Follow established patterns</li>
<li>Write clear, documented code</li>
<li>Test thoroughly</li>
</ul>
</div>
<div class="info-box warning">
<h3 style="margin-top: 0;">❌ Don't</h3>
<ul style="font-size: 0.9em;">
<li>Skip validation</li>
<li>Ignore error handling</li>
<li>Hardcode values</li>
</ul>
</div>
</section>
<!-- Slide 9: Summary -->
<section>
<h2>Summary</h2>
<ul>
<li>We covered the core concepts</li>
<li>Examined architecture and flow</li>
<li>Reviewed code examples</li>
<li>Discussed best practices</li>
</ul>
<div style="margin-top: 2rem; padding: 1rem; background: #f6f8fa; border-radius: 8px;">
<strong>Key Takeaway:</strong> One sentence summary of the main point
</div>
</section>
<!-- Slide 10: Q&A -->
<section class="title-slide">
<h2>Questions?</h2>
<p style="margin-top: 2rem; font-size: 0.8em;">
Contact: email@example.com<br>
Docs: https://docs.example.com
</p>
</section>
</div>
</div>
<!-- Reveal.js -->
<script src="https://cdn.jsdelivr.net/npm/reveal.js@5.0.4/dist/reveal.js"></script>
<script>
// Initialize Mermaid with pastel theme
mermaid.initialize({
startOnLoad: true,
theme: 'base',
themeVariables: {
primaryColor: '#FFE6E6',
primaryTextColor: '#333',
primaryBorderColor: '#999',
lineColor: '#666',
secondaryColor: '#E6F3FF',
tertiaryColor: '#E6FFE6',
quaternaryColor: '#FFF4E6',
quinaryColor: '#F0E6FF',
fontFamily: 'Inter, sans-serif'
}
});
// Initialize syntax highlighting
hljs.highlightAll();
// Initialize Reveal.js
Reveal.initialize({
hash: true,
slideNumber: true,
transition: 'slide',
backgroundTransition: 'fade',
progress: true,
controls: true,
keyboard: true,
overview: true,
center: false,
touch: true,
loop: false,
rtl: false,
fragments: true,
help: true,
showNotes: false,
autoPlayMedia: null,
preloadIframes: null,
mouseWheel: false,
hideInactiveCursor: true,
hideCursorTime: 5000,
width: 1280,
height: 720,
margin: 0.04,
minScale: 0.2,
maxScale: 2.0
});
// Re-render Mermaid diagrams when slides change
Reveal.on('slidechanged', () => {
mermaid.init(undefined, document.querySelectorAll('.mermaid'));
});
</script>
</body>
</html>

141
skills/product-manager/README.md Normal file
View File

@@ -0,0 +1,141 @@
# Claude Product Manager Skill
AI-powered Product Owner assistance for ticket management and refinement across multiple project management systems.
## What It Does
When you work with tickets in Linear, GitHub Issues, Local Markdown, or other supported PM systems, this Skill automatically activates to help you:
- **Create tickets** — Draft well-structured tickets with acceptance criteria from conversations
- **Analyze tickets** — Review for completeness, clarity, gaps, and dependencies
- **Propose amendments** — Suggest improvements based on code context or new information
- **Identify gaps** — Find missing coverage when breaking down epics
- **Generate questions** — Create structured refinement session discussion points
- **Plan work** — Suggest parallelization strategies and dependency analysis
## Supported PM Systems
- **Linear** — Full support via Linear MCP server
- **GitHub Issues** — Full support via GitHub CLI (`gh`)
- **Local Markdown** — File-based tickets in `docs/tickets/`
- Future systems (Jira, Azure Boards, etc.) via extensible connector framework
## Setup
### 1. Install the Plugin
This skill is part of the **pm-assistant** plugin available in the Claude Code Plugin Marketplace.
To install, use the marketplace installation command or manually install the plugin from the marketplace.
### 2. Configure Your PM System
**For Linear**:
1. Follow the [Linear MCP documentation](https://linear.app/docs/mcp) to set up the MCP server
2. Authenticate with Linear
3. Add `CLAUDE.md` configuration (see step 3)
**For GitHub Issues**:
1. Install GitHub CLI: https://cli.github.com/ or `brew install gh`
2. Authenticate: `gh auth login`
3. Verify git remote: `git remote get-url origin` (must be a GitHub repository)
4. Add `CLAUDE.md` configuration (see step 3)
**For Local Markdown**:
1. Create tickets directory: `mkdir -p docs/tickets`
2. Initialize counter: `echo "1" > docs/tickets/.ticket_counter`
3. Add `CLAUDE.md` configuration (see step 3)
### 3. Add Project Context (Required)
Create `CLAUDE.md` in your project root to declare which PM system to use:
**Example for Linear**:
```markdown
# CLAUDE.md
## Project Management
- **System**: Linear
- **Team Prefix**: PROD
- **Project**: Backend Services
```
**Example for GitHub Issues**:
```markdown
# CLAUDE.md
## Project Management
- **System**: GitHub-Issues
```
Note: Repository is auto-detected from git remote origin.
**Example for Local Markdown**:
```markdown
# CLAUDE.md
## Project Management
- **System**: Local-Markdown
- **Directory**: docs/tickets
```
The skill will use these settings for all operations in the project.
## How to Use
Simply describe what you need with tickets. The Skill activates automatically and works with your configured PM system:
```
Review the tickets for this sprint and identify any gaps
Create a ticket for implementing dark mode with acceptance criteria
What are the dependencies between PROD-100 and PROD-110?
Generate questions for our refinement session on the payment feature
Suggest improvements to this epic based on the code review
```
The Skill will:
1. Fetch relevant tickets from your PM system (Linear, GitHub Issues, or Local Markdown)
2. Analyze them using proven patterns
3. Present findings or proposals for review
4. **Wait for your explicit confirmation** before making changes
5. Apply updates and report results
## Documentation
- **SKILL.md** — Complete workflow guide and patterns
- **assets/ticket_template.md** — Ready-to-use templates
- **references/ticket_structure_guide.md** — Quality standards (system-agnostic)
- **references/analysis_patterns.md** — Six analysis workflows with examples
- **references/refinement_session_guide.md** — Refinement best practices
- **connectors/linear.md** — Linear MCP API reference and operations
- **connectors/local-markdown.md** — Local Markdown connector documentation
- **connectors/local-markdown/setup.md** — Setup instructions for local markdown
- **connectors/README.md** — Connector interface and extensibility guide
## Key Principles
✅ **Extensible architecture** — PM system-specific code isolated in connectors; supports Linear, GitHub Issues, and Local Markdown
✅ **Always proposes before acting** — Shows changes for your review
✅ **Requires explicit confirmation** — Never assumes approval
✅ **Specific and quoted** — References exact text when identifying issues
✅ **Explains rationale** — Shows why changes matter
✅ **Reusable patterns** — Analysis and refinement workflows system-agnostic
## Troubleshooting
| Problem | Solution |
|---------|----------|
| Skill not activating | Explicitly ask: "Use the product-manager skill to review these tickets..." |
| Team/project not found (Linear) | Add `CLAUDE.md` file with Linear team and project (see Setup step 3) |
| Can't find tickets (Linear) | Verify Linear is configured correctly in CLAUDE.md and MCP server is authenticated |
| Repository not detected (GitHub) | Verify git remote origin exists and is a GitHub URL: `git remote get-url origin` |
| `gh` command not found (GitHub) | Install GitHub CLI: https://cli.github.com/ or `brew install gh` |
| Not authenticated (GitHub) | Run `gh auth login` to authenticate with GitHub |
| Tickets directory not found (Local Markdown) | Create directory specified in CLAUDE.md: `mkdir -p docs/tickets` |
| System not declared | Add `CLAUDE.md` with `System` field set to Linear, GitHub-Issues, or Local-Markdown |
---
See **SKILL.md** for comprehensive documentation and workflow examples.

396
skills/product-manager/SKILL.md Normal file
View File

@@ -0,0 +1,396 @@
---
name: product-manager
description: Product Owner assistance for ticket refinement, epic breakdown, dependency analysis, and backlog management. Use this skill when shaping tickets, analyzing quality, identifying gaps, or generating refinement questions. For ticket data operations (get, list, create, update), the skill delegates to the ticket-assistant agent which supports Linear, Local Markdown, and GitHub Issues.
---
# Product Manager Skill
## Overview
This skill enables Product Owner workflows focused on **ticket shaping, structure, and best practices**:
- Refine tickets with proper structure and acceptance criteria
- Analyze tickets for gaps, clarity, completeness, and dependencies
- Break down epics into actionable sub-tickets
- Generate meaningful refinement session questions
- Propose amendments based on conversation context
**Ticket Data Operations**: All ticket access and manipulation (get, list, create, update) is delegated to the **ticket-assistant agent**, which handles Linear MCP, Local Markdown, and GitHub Issues operations.
## Architecture
```
User Request
↓
product-manager SKILL (shaping/best practices/analysis)
↓ (delegates data operations)
ticket-assistant AGENT (Linear MCP / Local Markdown / GitHub CLI CRUD)
↓
[Linear MCP] or [Markdown Files] or [GitHub CLI]
```
## Core Capabilities
### 1. Create Tickets from Conversation
**Scenario**: "Create a ticket for this feature with acceptance criteria" or "Based on the conversation transcript create epic with tickets/ticket"
**Process**:
1. Extract requirements from conversation context
2. Use ticket template from `assets/ticket_template.md`
3. Structure as simple or complex ticket based on scope
4. Apply appropriate type labels (Feature, Bug, Enhancement, etc.)
5. Present proposal to user for review
6. **Use AskUserQuestion tool for confirmation**: Wait for explicit approval before proceeding
7. **After user confirms**: Delegate to ticket-assistant agent to create ticket
8. Report created ticket with ID and link
**Guidelines**:
- Refer to `references/ticket_structure_guide.md` for formatting standards
- Include acceptance criteria for complex work
- Flag open questions when scope is unclear
- Suggest dependencies if work relates to existing tickets
- **Content focus**: Extract user needs and business value; avoid code snippets
- **Include technical details when**:
- Explicitly instructed to include them
- Deviating from standard conventions or patterns
- Non-standard approach requires documentation
- Critical technical constraints that impact implementation
### 2. Propose Ticket Amendments
**Scenario**: "Are there any wrong assumptions in the ticket?" or "Based on the conversation transcript suggest adjustments to epic XXX-123"
**Process**:
1. Delegate to ticket-assistant agent to fetch existing ticket/epic
2. Analyze current state (description, acceptance criteria, scope)
3. Cross-reference with provided context (code, conversation, etc.)
4. Use patterns from `references/analysis_patterns.md` to identify:
- Assumption mismatches
- Scope gaps or overreach
- Missing edge cases or error handling
- Outdated requirements
5. Present proposed changes:
- "Current state" (quote from ticket)
- "Suggested changes" (with rationale)
- "Questions for team" (if needed)
6. **Use AskUserQuestion tool for confirmation**: Wait for explicit approval before proceeding
7. **After user confirms**: Delegate to ticket-assistant agent to update ticket
8. Report changes applied
**Guidelines**:
- Be specific: quote the problematic text
- Explain the "why" behind each suggested change
- Distinguish between critical (must fix) and nice-to-have improvements
- Use AskUserQuestion tool if context is ambiguous or requires clarification
### 3. Analyze Tickets for Quality
**Scenario**: "Review existing Linear tickets for completeness, clarity, dependencies, open questions" for range AIA-100 through AIA-110
**Process**:
1. Delegate to ticket-assistant agent to fetch tickets in range
2. For each ticket, evaluate against criteria:
- **Clarity**: Title, description, acceptance criteria
- **Completeness**: All required fields, edge cases covered
- **Dependencies**: Blocks/Blocked-by relationships identified
- **Open questions**: Uncertainties flagged
3. Use `references/analysis_patterns.md` Pattern 4 for systematic evaluation
4. Compile findings:
- Strong tickets (ready for development)
- Needs work (specific improvements recommended)
- Needs breakdown (too large)
- Blocked (waiting on decisions)
5. Present report with:
- Summary per ticket
- Recommended actions
- Highest-priority refinements needed
**Guidelines**:
- Use consistent evaluation structure
- Highlight both strengths and issues
- Provide specific, actionable recommendations
- Flag patterns across multiple tickets (e.g., all missing error handling)
### 4. Identify Gaps in Epic Coverage
**Scenario**: "Identify gaps in the planned tickets for epic XXX-123"
**Process**:
1. Delegate to ticket-assistant agent to fetch epic and sub-tickets
2. Analyze epic scope vs. ticket coverage using `references/analysis_patterns.md` Pattern 1:
- Frontend/UI components
- Backend services and APIs
- Testing and QA work
- Documentation and knowledge base
- Deployment or infrastructure
- Edge cases and error scenarios
3. Present findings:
- Identified gaps with context
- Suggested new tickets for each gap
- Estimated scope per gap
4. **Use AskUserQuestion tool for confirmation**: Present options to create all tickets, select specific ones, or review proposals first
5. **After user confirms**: Delegate to ticket-assistant agent to create tickets
**Guidelines**:
- Be thorough but realistic (not everything needs a separate ticket)
- Group related gaps (e.g., multiple API endpoints in one ticket)
- Consider team's estimation approach when scoping gaps
- Link new tickets to epic as subtickets
### 5. Analyze Dependencies and Suggest Parallelization
**Scenario**: User asks about dependencies between tickets or how to parallelize work
**Process**:
1. Delegate to ticket-assistant agent to fetch relevant tickets
2. Use `references/analysis_patterns.md` Pattern 3:
- Extract explicit Blocks/Blocked-by relationships
- Identify implicit dependencies
- Find critical path (work that must complete first)
- Group by parallelizable tracks
3. Present parallelization strategy:
- Work that can happen simultaneously
- Critical path dependencies
- Recommended team allocation
4. Suggest implementation sequence
**Guidelines**:
- Consider frontend/backend can often run in parallel if API contract is clear
- Testing can often run alongside implementation if setup is clear
- Documentation can start early with skeleton/outline
- Infrastructure work often critical path
### 6. Generate Refinement Session Questions
**Scenario**: "Generate questions for the next refinement session for tickets XXX-100 through XXX-110"
**Process**:
1. Delegate to ticket-assistant agent to fetch ticket range
2. Analyze each ticket for uncertainty patterns:
- Missing acceptance criteria
- Ambiguous requirements
- Unknown trade-offs
- Implicit assumptions
- Unclear edge cases
3. Use `references/refinement_session_guide.md` and `references/analysis_patterns.md` Pattern 5
4. Generate questions organized by:
- **Critical blockers**: Must resolve first
- **Design/Technical questions**: Needed before building
- **Edge cases**: Clarify completeness
- **Dependencies**: Identify coordination needs
- **Success metrics**: Define what "done" means
5. Present as structured question set with:
- Target audience (Product, Engineering, Design)
- Why the question matters
- Suggested answers or options
**Guidelines**:
- Prioritize high-impact questions first
- Frame as open-ended (not leading)
- Group related questions by theme
- Note interdependencies between questions
- Suggest time-boxing for discussion
## Reference Materials
### Ticket Structure and Templates
- **`references/ticket_structure_guide.md`** - Title guidelines, label categories, description formats, acceptance criteria best practices, refinement checklist, red flags
- **`assets/ticket_template.md`** - Ready-to-use templates for simple/complex/bug/epic tickets
### Analysis Patterns
- **`references/analysis_patterns.md`** - 6 structured reasoning patterns:
1. Identifying gaps in epic coverage
2. Detecting assumption mismatches
3. Dependency analysis and parallelization
4. Clarity and completeness review
5. Generating refinement session questions
6. Epic analysis and adjustment suggestions
### Refinement Sessions
- **`references/refinement_session_guide.md`** - Question generation strategies, facilitation tips, sample agendas, post-refinement checklist
### When to Use Each Analysis Pattern
| Pattern | Trigger Question | Reference |
|---------|------------------|-----------|
| Gap Identification | "Identify gaps in epic XXX" | `analysis_patterns.md` Pattern 1 |
| Assumption Mismatch | "Are there wrong assumptions?" | `analysis_patterns.md` Pattern 2 |
| Dependency Analysis | "What are dependencies?" | `analysis_patterns.md` Pattern 3 |
| Quality Review | "Review tickets for completeness" | `analysis_patterns.md` Pattern 4 |
| Refinement Questions | "Generate questions for session" | `analysis_patterns.md` Pattern 5, `refinement_session_guide.md` |
| Epic Adjustment | "Suggest adjustments to epic" | `analysis_patterns.md` Pattern 6 |
## Workflow: Create and Propose
All creation and amendment operations follow this pattern:
### Step 1: Gather Context
- User provides requirements (conversation, transcript, existing ticket)
- If ticket data is needed, delegate to ticket-assistant agent
### Step 2: Analyze and Draft
- Use appropriate patterns from `references/analysis_patterns.md`
- Follow structure from `references/ticket_structure_guide.md` or templates
- Draft ticket/amendment with complete context
### Step 3: Present for Review
- Show "current state" and "proposed state" for amendments
- Show "proposed ticket" for new tickets
- Include rationale for each decision
- Use AskUserQuestion tool if clarification is needed
### Step 4: Wait for Confirmation
- **Use AskUserQuestion tool** to get explicit user confirmation before proceeding
- **Do not proceed** until user confirms via the tool response
- Offer to adjust draft if user suggests changes
- Re-present adjusted version and confirm again using AskUserQuestion
### Step 5: Apply Changes
- Delegate to ticket-assistant agent to create/update tickets
- Agent handles all PM system-specific operations
### Step 6: Report Results
- Confirm what was created/updated
- Provide ticket ID and Link (if available)
- Ask: "What would you like to do next?"
## Best Practices
### Ticket Quality
- Read `references/ticket_structure_guide.md` for quality standards
- Ensure titles are specific and action-oriented
- Include acceptance criteria for complex work
- Flag open questions when scope is unclear
- Link dependencies explicitly
### Analysis Completeness
- Quote specific text when identifying issues
- Explain the "why" behind recommendations
- Distinguish between facts (what's written) and inferences
- Flag assumptions clearly
- Suggest options with trade-offs when multiple paths exist
### User Confirmation Protocol
- Always show proposals before applying
- **Use AskUserQuestion tool** to get explicit user confirmation with clear options
- Wait for confirmation response from the tool before proceeding
- Never assume approval
- Offer revision if user suggests changes
- Re-present for approval after revisions (using AskUserQuestion again)
### Delegating to Agent
- Use ticket-assistant agent for all data operations (get, list, create, update, search)
- Agent handles PM system detection and operations
- Focus skill logic on analysis, shaping, and best practices
## Using AskUserQuestion for User Input
When user input is required during workflow execution, use the **AskUserQuestion** tool to present structured options. This ensures clear, actionable choices and reduces ambiguity.
### When to Use AskUserQuestion
Use the tool for:
1. **Clarifying questions during analysis** - When requirements, scope, or context needs clarification
2. **Confirmation before actions** - Before creating or updating tickets in the PM system
Do NOT use for:
- Open-ended conversational follow-ups ("What would you like to do next?")
- Refinement session questions (those are for human facilitators)
### Example 1: Clarifying Requirements During Analysis
**Scenario**: Analyzing a ticket but scope is ambiguous between two interpretations.
```
Use AskUserQuestion tool with:
{
"questions": [{
"question": "The ticket mentions 'email notifications' but doesn't specify the scope. What should be included?",
"header": "Scope",
"multiSelect": true,
"options": [
{
"label": "Digest emails",
"description": "Scheduled summary emails sent daily/weekly"
},
{
"label": "Real-time notifications",
"description": "Immediate emails when events occur"
},
{
"label": "Transactional emails",
"description": "System-triggered emails (password reset, confirmations)"
}
]
}]
}
```
### Example 2: Confirming Before Creating Tickets
**Scenario**: Identified 3 gaps in epic coverage, ready to create tickets.
```
Use AskUserQuestion tool with:
{
"questions": [{
"question": "I've identified 3 missing tickets for the email digest epic. Should I create them?",
"header": "Create Tickets",
"multiSelect": false,
"options": [
{
"label": "Create all 3 tickets",
"description": "Create tickets for: UI preferences component, end-to-end testing, and scheduled job setup"
},
{
"label": "Show me the proposals first",
"description": "Present detailed ticket proposals for review before creating"
},
{
"label": "Create only high-priority ones",
"description": "Create tickets for UI component and testing, defer infrastructure work"
}
]
}]
}
```
### Guidelines for Effective Questions
**Structure**:
- Use clear, specific question text
- Provide 2-4 options (not just yes/no when possible)
- Include descriptions explaining what each option means
- Use `multiSelect: true` only when choices are not mutually exclusive
**Headers**:
- Keep short (max 12 chars): "Scope", "Approach", "Confirm", "Priority"
- Describes the decision type
**Options**:
- Label: Concise choice (1-5 words)
- Description: Explain implications or what happens if chosen
## Directory Structure
```
plugins/pm-assistant/skills/ticket-assistant/
├── SKILL.md # This file
├── README.md # User-facing documentation
├── assets/
│ └── ticket_template.md # Ticket templates
├── references/ # Domain knowledge
│ ├── ticket_structure_guide.md # Ticket quality standards
│ ├── analysis_patterns.md # Analysis methodologies
│ └── refinement_session_guide.md # Refinement facilitation
└── connectors/ # PM system reference (optional)
└── linear.md # Linear MCP quick reference (if needed)
```
## Notes
- Maximum 500 words per ticket (concise content)
- All timestamps use ISO 8601 format
- Descriptions support Markdown formatting
- Always delegate ticket data operations to ticket-assistant agent
- Focus on analysis, shaping, and best practices in this skill

264
skills/product-manager/assets/ticket_template.md Normal file
View File

@@ -0,0 +1,264 @@
# Ticket Template
Use this template as a starting point for new tickets. Adapt based on complexity:
- **Simple tickets**: Use minimal template (title + brief what/why/how)
- **Complex features**: Use full template with all sections
- **Bugs**: Use bug-specific template (STR + Expected vs Actual)
## Simple Ticket Template
```
Title: [Action] [What] [Where if specific]
[1-2 sentence context about why this matters]
[Brief: what needs to change]
Acceptance Criteria:
- [ ] Criterion 1
- [ ] Criterion 2
```
## Complex Feature Ticket Template
```
Title: [Action] [What] for [User Type/Context]
## Context
[2-3 sentences explaining why this matters]
- Problem it solves:
- User impact:
- Business value:
## Requirements
- Functional requirement 1
- Functional requirement 2
- Non-functional requirement (performance, compatibility, etc.)
- Integration points with [System X]
## Acceptance Criteria
### Given-When-Then Examples
Given [initial state]
When [action taken]
Then [expected outcome]
### Additional Checkboxes
- [ ] API endpoint returns 200 status
- [ ] Error handling for [edge case] returns 400
- [ ] Documentation updated
- [ ] Test coverage at [X]%
## Open Questions
- [Engineering] How should we handle [technical concern]?
- [Product] What's the expected behavior for [scenario]?
- [Business] Do we need [compliance/security feature]?
## Dependencies
- Depends on: [Ticket ID if applicable]
- Blocks: [Ticket ID if applicable]
## Estimate
[Story points or T-shirt size if using estimation]
```
## Bug Ticket Template
```
Title: [Bug] [Component] [Symptom]
## Steps to Reproduce
1. Navigate to [page/screen]
2. [Action 1]
3. [Action 2]
4. [Observe result]
## Expected Behavior
[What should happen]
## Actual Behavior
[What is actually happening]
## Environment
- Browser: [Chrome 120 on macOS / etc.]
- Device: [Device model]
- OS: [OS and version]
- Network: [Stable / Flaky / etc.]
- User Type: [Admin / Regular user / etc.]
## Additional Context
[Screenshots, error logs, data samples if helpful]
## Severity
- [ ] Critical (Service down, data loss, security)
- [ ] High (Core feature broken, widespread impact)
- [ ] Medium (Feature partially broken, workaround exists)
- [ ] Low (Minor UI issue, edge case, cosmetic)
## Acceptance Criteria
- [ ] Bug reproduction confirmed
- [ ] Root cause identified and documented
- [ ] Fix implemented and tested
- [ ] Regression test added
- [ ] Verified in [environment]
```
## Epic Ticket Template
```
Title: [Capability] for [User/Team/Domain]
## Overview
[1-2 sentence description of the epic scope]
## Goals
- Goal 1: [Specific, measurable outcome]
- Goal 2: [Specific, measurable outcome]
## Scope
**In Scope**:
- Feature/capability 1
- Integration with [System X]
- Support for [User type/scenario]
**Out of Scope** (explicitly defer):
- Feature that's related but separate
- Advanced feature deferred to later
## Success Metrics
- [Metric 1]: Target [X] by [Date]
- [Metric 2]: Target [X] by [Date]
## Key Dependencies
- Requires: [System/Feature that must be in place]
- Blocks: [Work that will be blocked on this]
- Integrates with: [Related systems]
## Acceptance Criteria
- [ ] All child tickets completed
- [ ] Documentation complete
- [ ] [User type] can [primary use case]
- [ ] Performance target [X] met
- [ ] Rollout to [X]% of users successful
## Open Questions
- [Product] Should we support [feature variant]?
- [Engineering] Is [architecture choice] the right approach?
- [Design] What's the rollout experience?
## Planned Breakdown (Initial)
- [Ticket category 1]: e.g., Backend API implementation
- [Ticket category 2]: e.g., Frontend UI
- [Ticket category 3]: e.g., Testing and validation
- [Ticket category 4]: e.g., Documentation
```
## Notes on Template Usage
**Title Writing Tips**:
- ✅ "Add CSV export for user data"
- ✅ "[Bug] Email parser fails on UTF-8 domains"
- ✅ "[Epic] Mobile app for iOS"
- ❌ "Export feature"
- ❌ "Parser issue"
**When to use Complex Template**:
- Feature impacts multiple systems
- Epic or large feature
- Cross-team dependencies
- Performance or security considerations
- Unclear requirements or assumptions
**When to use Simple Template**:
- UI/text changes
- Small bug fixes
- Documentation updates
- Isolated improvements
**Accepting Criteria Tips**:
- Make them testable without ambiguity
- Include both happy path and error cases
- For complex logic, use Given-When-Then format
- For simple features, checkboxes are fine
- Avoid "code is clean" or vague criteria
## Content Guidelines
**Default: Product-Centric Focus**
Tickets should prioritize user value and business outcomes:
✅ **Good - Product-focused**:
```
Title: Enable users to export their data
Context:
Users need ability to download their data for backup and compliance purposes.
This supports GDPR requirements and builds user trust.
Requirements:
- Export button accessible from user profile
- Support CSV and JSON formats
- Include all user data except internal system fields
Acceptance Criteria:
- [ ] User can initiate export from profile page
- [ ] System generates file within 30 seconds
- [ ] Downloaded file contains complete user data
- [ ] Format selection (CSV/JSON) works correctly
```
❌ **Poor - Too implementation-heavy**:
```
Title: Add CSV export endpoint
Context:
Need to implement CSV export using fast-csv library.
Code: const csv = require('fast-csv'); function exportData() { ... }
Requirements:
- Create /api/export endpoint
- Use fast-csv for generation
- Return response with proper headers
```
**Including Technical Details**
Include technical specifics when:
1. **Explicitly requested**:
```
User: "Create ticket for payment processing. Make sure to note we're using Stripe, not our usual PayPal."
✅ Ticket includes:
Technical Note: Use Stripe payment gateway (deviation from standard PayPal integration)
due to better support for recurring subscriptions.
```
2. **Convention deviation**:
```
User: "We need to use Redis for this caching layer instead of Memcached"
✅ Ticket includes:
Technical Note: Implement caching with Redis (deviation from Memcached standard)
to support pub/sub for real-time invalidation.
```
3. **Critical architectural constraint**:
```
✅ Ticket includes:
Technical Constraint: Use event-driven architecture with message queue
to support asynchronous processing and avoid blocking user requests.
```
**What NOT to include**:
❌ Avoid:
- Code snippets or function implementations
- Specific variable names or method signatures
- Sample code from conversations or documentation
✅ Instead use:
- Architectural patterns: "Use Observer pattern for notifications"
- Technology choices: "Implement with WebSockets for bidirectional communication"
- Design constraints: "Must support horizontal scaling"

359
skills/product-manager/references/analysis_patterns.md Normal file
View File

@@ -0,0 +1,359 @@
# Ticket and Epic Analysis Patterns
This guide provides structured approaches for analyzing tickets and epics using LLM reasoning.
## Overview
Analysis tasks leverage LLM reasoning to:
- Identify gaps and missing tickets
- Detect mismatches between ticket assumptions and code reality
- Find dependencies and relationships
- Evaluate ticket clarity and completeness
- Generate thoughtful refinement questions
## Pattern 1: Identifying Gaps in Epic Coverage
**Scenario**: User wants to identify missing tickets for an epic (e.g., "Identify gaps in epic XXX-123").
### Process
1. **Fetch the epic**:
- Get the epic issue to understand scope, description, acceptance criteria
- Parse the epic's stated goals and requirements
2. **Fetch all subtickets**:
- Query: `parent:"EPIC-ID"`
- List all child tickets
- Map coverage: which parts of the epic have tickets?
3. **Analyze coverage**:
- Compare epic description against existing tickets
- Identify missing areas:
- Frontend/UI components not covered
- Backend services or APIs not covered
- Testing or QA work not covered
- Documentation or knowledge base gaps
- Deployment or infrastructure work not covered
- Look for edge cases or error scenarios
- **Content filtering**:
- Extract user needs and business value
- Translate code discussions to high-level requirements
- Exclude code snippets unless explicitly requested
- Include technical details when deviating from conventions
4. **Present findings**:
- List identified gaps with context
- Suggest new tickets for uncovered work
- Include estimated scope for each gap
### Example Analysis Structure
**Epic**: "Implement email digest feature"
**Current tickets**:
- AIA-100: Design email digest schema
- AIA-101: Build digest generation API
- AIA-102: Create email templates
**Identified gaps**:
- [ ] UI component: Digest frequency preferences (suggested: 2-3 points)
- [ ] Testing: End-to-end digest flow with real email delivery
- [ ] Documentation: Digest API documentation and examples
- [ ] Infrastructure: Set up scheduled job for digest generation (cron/task queue)
## Pattern 2: Detecting Assumption Mismatches
**Scenario**: User asks "Are there any wrong assumptions in this ticket?" (often comparing ticket description to actual code implementation).
### Process
1. **Extract assumptions from ticket**:
- Read ticket description, acceptance criteria, requirements
- Identify explicit assumptions:
- "API returns JSON array"
- "User already authenticated"
- "Database table exists with these fields"
- Identify implicit assumptions:
- "Feature X is already implemented"
- "Libraries are available in codebase"
- "System can handle concurrent requests"
2. **Cross-reference with provided context**:
- User may provide code snippets, implementation details, or codebase structure
- Compare assumptions against actual state
- Identify mismatches:
- API returns different format
- Prerequisites not yet implemented
- Different database schema
- Performance constraints
- Library incompatibilities
3. **Categorize mismatches**:
- **Critical**: Breaks implementation (e.g., "API structure wrong")
- **High**: Requires significant rework (e.g., "Missing prerequisite")
- **Medium**: Needs clarification or small adjustment
- **Low**: Minor edge case or optimization
4. **Present findings with remediation**:
- Flag each mismatch clearly
- Explain impact on implementation
- Suggest updated acceptance criteria or requirements
- Use AskUserQuestion tool to confirm: "Should we update the ticket or is there missing context?"
### Example Mismatch Detection
**Ticket assumption**: "Email parser API returns structured fields: { sender, subject, body, attachments }"
**Code reality**: "Parser returns raw MIME structure; field extraction not yet implemented"
**Mismatch**: Critical
- Ticket describes endpoint as done; actually needs field extraction layer
- Acceptance criteria unrealistic for current implementation
- **Suggested fix**: Split into (1) MIME parsing, (2) field extraction, (3) API endpoint
## Pattern 3: Dependency Analysis and Parallelization
**Scenario**: User wants to understand dependencies across tickets for parallel work.
### Process
1. **Extract dependencies from ticket relationships**:
- Review Blocks/Blocked-by relationships
- Look for implicit dependencies:
- "Requires backend API" → ticket mentions API endpoint
- "Needs database migration" → schema changes
- "Depends on design decision" → tickets waiting on decisions
2. **Identify critical path**:
- Work that must complete before others can start
- Usually: design → backend → frontend → testing
3. **Group by parallelizable tracks**:
- Frontend UI work (if API contract defined)
- Backend API implementation
- Testing and QA scenarios
- Documentation and knowledge base
- Infrastructure/deployment work
4. **Suggest optimal sequence**:
- Propose which work can happen in parallel
- Identify blockers that must resolve first
- Recommend team allocation to maximize parallelization
### Example Parallelization
**Tickets for feature**: Email digest feature (AIA-100 to AIA-105)
**Analysis**:
- AIA-100 (Design schema) - critical path start
- AIA-101 (Backend API) - depends on AIA-100 ✓ can start after design
- AIA-102 (Email templates) - independent ✓ can start immediately
- AIA-103 (Frontend UI) - depends on AIA-101 API contract
- AIA-104 (Testing) - depends on AIA-101 being runnable
- AIA-105 (Documentation) - can start after AIA-100
**Suggested parallelization**:
1. **Start simultaneously**: AIA-100 (design), AIA-102 (templates)
2. **Once AIA-100 done**: Start AIA-101 (backend), AIA-105 (docs)
3. **Once AIA-101 done**: Start AIA-103 (frontend), AIA-104 (testing)
## Pattern 4: Clarity and Completeness Review
**Scenario**: User asks "Review existing Linear tickets for completeness, clarity, dependencies, open questions" for a range of tickets.
### Process
1. **Fetch all tickets** in the specified range (e.g., AIA-100 through AIA-110)
2. **Evaluate each ticket against criteria**:
**Clarity Assessment**:
- Is title specific and action-oriented?
- Is description concise and understandable?
- Are acceptance criteria testable and specific?
- Would a developer confidently estimate and implement?
**Completeness Check**:
- Does complex ticket have acceptance criteria?
- Are bugs reproducible (steps provided)?
- Are features properly scoped?
- Are dependencies identified?
- Are open questions flagged?
**Dependency Verification**:
- Are blocking relationships explicitly set?
- Could work run in parallel if clearer?
- Are implicit dependencies made explicit?
**Open Questions Assessment**:
- Are uncertainties flagged?
- Are questions assignable to right parties?
3. **Compile findings**:
- Create summary per ticket
- Highlight strengths and issues
- Rank by urgency of refinement needed
4. **Present with recommendations**:
- Strong tickets (ready for development)
- Needs clarity (specific improvements recommended)
- Needs breakdown (too large or complex)
- Blocked by decisions (needs input from product/design)
### Evaluation Template
For each ticket, assess:
```
Ticket: AIA-XXX - [Title]
Status: [Ready/Needs Work/Blocked]
Clarity: [✓/⚠/✗] with reason
Completeness: [✓/⚠/✗] with reason
Dependencies: [✓/⚠/✗] with reason
Questions: [✓/⚠/✗] with reason
Issues found:
- [Issue 1 with recommendation]
Recommended next step:
- [Action needed]
```
## Pattern 5: Generating Refinement Session Questions
**Scenario**: User asks "Generate questions for the next refinement session for tickets XXX-100 through XXX-110".
### Process
1. **Fetch tickets** in the range
2. **Identify uncertainty patterns**:
- Missing acceptance criteria
- Ambiguous requirements
- Conflicting specs
- Implicit assumptions
- Unknown edge cases
- Unclear priorities or value
3. **Generate clarifying questions** organized by type:
**For Product/Business**:
- "What's the priority of this feature relative to X?"
- "Who is the primary user and what problem does this solve?"
- "What's the expected timeline/deadline?"
- "Are there any compliance or regulatory requirements?"
**For Engineering**:
- "Is this technically feasible with current stack?"
- "Are there performance constraints we should consider?"
- "Does this require changes to authentication/authorization?"
- "What's the rollout strategy (feature flag, gradual, etc.)?"
**For Design/UX**:
- "Have we designed the user flows for this?"
- "Are there accessibility requirements?"
- "What's the visual/interaction pattern from existing UI?"
**For All**:
- "How does this integrate with existing feature X?"
- "What happens in error scenarios?"
- "What's the success metric for this?"
4. **Organize questions strategically**:
- Start with high-impact, blockers
- Group by theme or epic
- Flag critical unknowns
- Note dependencies between questions
### Example Question Set
**For epic "Email digest feature" refinement session**:
**Critical blockers** (must resolve first):
- [Product] Is the digest frequency (daily/weekly/monthly) configurable per user or system-wide?
- [Engineering] Can our email system handle the volume of digest sends? Should we batch them?
**Design questions** (needed before building):
- [Design] Have we designed the digest preview UI?
- [All] What unsubscribe mechanism do we need for digests?
**Edge cases** (clarify before acceptance):
- [Product] What happens if a user has no emails in the digest period?
- [Engineering] How do we handle timezone differences for "weekly" digests?
## Pattern 6: Epic Analysis and Adjustment Suggestions
**Scenario**: User wants "Based on the conversation transcript suggest adjustments to the epic XXX-123".
### Process
1. **Fetch the epic** with full description and current subtickets
2. **Analyze conversation transcript** for:
- New insights or requirements not in epic description
- Stakeholder concerns or constraints
- Changed priorities or scope
- Technical challenges or trade-offs discussed
- User feedback or use cases mentioned
3. **Cross-reference with current epic**:
- What's aligned between epic description and conversation?
- What's missing from epic description?
- What's in epic that wasn't discussed or is outdated?
- Are subtickets still appropriate?
4. **Suggest adjustments**:
- Update epic description with new context
- Recommend new tickets for discussion outcomes
- Suggest removing or deferring scope
- Highlight dependencies discovered in discussion
- Flag trade-offs for decision
5. **Present as proposed amendments**:
- "Current epic description" vs. "Suggested updates"
- "Current subtickets" vs. "Suggested changes"
- Rationale for each change
### Amendment Template
```
Epic: XXX-123 - [Current Title]
Current scope: [quote from description]
Suggested scope updates:
- Add: [new requirement or insight]
- Remove: [scope to defer]
- Clarify: [ambiguous part with suggested rewording]
New subtickets suggested:
- [Ticket with estimated scope]
Subtickets to reconsider:
- [Ticket that may no longer fit]
Dependencies or blockers discovered:
- [Dependency or constraint]
```
## General Analysis Guidelines
**Always**:
- Quote specific text from tickets/epics in findings
- Provide specific, actionable recommendations
- Explain the "why" behind observations
- Distinguish between facts (what's written) and inferences (what's implied)
- Flag assumptions clearly
**Consider**:
- Team's estimation approach (story points, t-shirt, none)
- Sprint velocity and capacity
- Current backlog health and priorities
- Existing patterns in ticket structure (to match style)
**When unsure**:
- Use AskUserQuestion tool for clarifying questions
- Flag as open question for refinement
- Suggest options with trade-offs
- Don't assume team preferences or standards

333
skills/product-manager/references/refinement_session_guide.md Normal file
View File

@@ -0,0 +1,333 @@
# Refinement Session Guide
This guide explains how to prepare for and facilitate refinement sessions, including generating meaningful discussion questions.
## Refinement Session Overview
Refinement sessions are where product teams:
- Discuss upcoming work (next 2-3 sprints)
- Break down epics into actionable tickets
- Clarify requirements and acceptance criteria
- Identify dependencies and blockers
- Estimate complexity (if using estimation)
- Align on priorities
## Pre-Refinement: Generating Questions
**Scenario**: "Generate questions for the next refinement session for tickets XXX-100 through XXX-110"
### Question Generation Strategy
Generate questions that:
1. **Unblock implementation** - Remove technical uncertainties
2. **Clarify value** - Ensure everyone understands the "why"
3. **Surface dependencies** - Identify work that affects other work
4. **Challenge assumptions** - Find gaps in thinking
5. **Enable estimation** - Provide clarity for sizing complexity
### Question Categories and Examples
#### 1. Scope and Value Questions
**Product/Business focus**:
- "What's the primary user need this solves?"
- "Why now? What drives the priority?"
- "How does this relate to our OKRs?"
- "What's the definition of success?"
- "Who should we talk to validate this with users?"
**When to use**: For new features, roadmap items, or items with unclear "why"
#### 2. Technical Feasibility Questions
**Engineering focus**:
- "Is our current tech stack a good fit for this?"
- "Are there performance or scalability concerns?"
- "Do we need new infrastructure or tooling?"
- "Is this technically feasible in the next sprint?"
- "What technical debt might block this?"
**When to use**: Complex features, infrastructure work, new integrations
#### 3. Design and UX Questions
**Design focus**:
- "Have we designed this user flow?"
- "Are there accessibility requirements?"
- "How does this fit our existing design system?"
- "What's the mobile experience like?"
- "Should we prototype or validate first?"
**When to use**: Customer-facing features, UI changes
#### 4. Dependency and Integration Questions
**Cross-functional**:
- "Does this depend on other work in progress?"
- "Could this block other teams or projects?"
- "Does this integrate with [system X]? How?"
- "What APIs or data do we need from [team Y]?"
- "What's the integration test strategy?"
**When to use**: Any feature involving multiple systems, teams, or components
#### 5. Edge Cases and Error Handling
**Completeness focus**:
- "What happens if [error scenario]?"
- "How do we handle concurrent requests?"
- "What's the rollback strategy if things go wrong?"
- "Are there rate limits or capacity considerations?"
- "What about inactive/deleted users/data?"
**When to use**: Critical systems, features affecting data integrity, payment/security
#### 6. Decision-Required Questions
**Flag blockers**:
- "Do we need a design decision before starting?"
- "Should we do [approach A] or [approach B]? What are the trade-offs?"
- "Is this a platform-wide change requiring architectural decision?"
- "Should we spike this first to reduce uncertainty?"
**When to use**: Items with multiple paths forward or architectural implications
#### 7. Rollout and Deployment Questions
**Operations focus**:
- "Should this go behind a feature flag?"
- "How do we roll this out without impacting users?"
- "What monitoring/alerts do we need?"
- "Is there a canary/gradual rollout strategy?"
- "What's the rollback procedure?"
**When to use**: User-facing changes, infrastructure changes, high-impact work
### Question Framing for Different Audiences
**For Engineering-heavy sessions**:
- Focus on technical feasibility and dependencies
- Include spike/investigation questions
- Address edge cases and error scenarios
- Discuss performance and testing implications
**For Product-heavy sessions**:
- Emphasize user value and success metrics
- Clarify scope and priorities
- Discuss trade-offs between features
- Identify missing user research or validation
**For Cross-functional sessions**:
- Start with "why" (value and goals)
- Surface dependencies early
- Identify design/technical gaps
- End with "what's next" (work plan)
## Sample Refinement Question Sets
### Example 1: New Feature (Email Digest)
```
**Value & Scope**:
- What problem does email digest solve for users?
- Who's the primary user? What's their current workflow?
- Should frequency be configurable per user or system-wide?
**Technical**:
- Can our email system handle batch sending this volume?
- Should we use a background job or scheduled task?
- What email format (HTML/plain text/both)?
**Edge Cases**:
- What if user has no emails in the period?
- How do we handle timezone differences?
- Unsubscribe mechanism?
**Dependencies**:
- Does this block or depend on other email features?
- Do we need design approval before building?
**Success**:
- How do we measure if this succeeds?
- What's the rollout timeline?
```
### Example 2: Bug Fix (Parser Failing on Special Characters)
```
**Clarification**:
- What's the impact? How many users affected?
- Which special characters cause failures?
- Is this a security issue or just a UX problem?
**Root Cause**:
- Have we root-caused this?
- Is it encoding, parsing, or validation?
**Solution Scope**:
- Should we fix just these characters or handle all UTF-8?
- Do we need to update error messages?
- Should we add input validation on the frontend?
**Testing**:
- What test cases should we add?
- How do we prevent regression?
**Rollout**:
- Is this a hotfix or can we batch with other parser work?
- Do we need to handle existing data that's affected?
```
### Example 3: Infrastructure Work (Database Migration)
```
**Why and When**:
- Why do we need this migration now?
- What's the impact of not doing it?
- Is this blocking feature work?
**Approach**:
- What's the migration strategy (zero-downtime? maintenance window?)?
- Do we need a feature flag or gradual rollout?
- What's the rollback plan?
**Scope**:
- Affected tables and data volumes?
- Performance impact?
- Monitoring and alerting?
**Dependencies**:
- Deployment sequence with other work?
- Do other teams need to prepare?
**Communication**:
- Do users need notification?
- What's the customer-facing impact?
```
## During Refinement: Using Questions to Guide Discussion
### Facilitation Tips
**Opening** (set context):
- "We're refining the next 2 sprints' work"
- "Goal is to clarify scope, surface unknowns, and identify dependencies"
- "It's okay if we don't have all answers—we'll capture questions for resolution"
**Present the work** (overview):
- Share epic or feature theme
- Briefly describe what we're working on
- Set the context for why now
**Ask clarifying questions** (engagement):
- Start with scope and value: "What problem does this solve?"
- Move to feasibility: "Is this technically doable?"
- Explore details: "What about edge case X?"
- Flag unknowns: "Do we need design input on this?"
**Capture decisions** (outcomes):
- What did we decide?
- What's still open?
- Who owns next steps?
**Identify follow-ups** (action items):
- Spike investigations
- Design reviews needed
- External dependencies
- Clarifications from stakeholders
### Handling "I Don't Know" Responses
When questions can't be answered:
1. **Capture as open question**:
- Assign to appropriate person/team
- Link in ticket for traceability
- Flag as blocking or non-blocking
2. **Offer options to move forward**:
- "Should we make an assumption to proceed?"
- "Do we need a spike to validate?"
- "Can we defer this to a separate ticket?"
3. **Note dependency**:
- "This is blocked on [decision/clarification]"
- "Engineering to spike approach by [date]"
## Post-Refinement: Ticket Quality Checklist
After refinement, ensure tickets are ready for development:
### Before Moving to Sprint
**For each ticket**, verify:
- [ ] **Title** is specific and action-oriented
- [ ] **Description** is concise (150-200 words) and answers: what, why, how
- [ ] **Type label** applied (Feature, Bug, Enhancement, etc.)
- [ ] **Acceptance criteria** are testable and specific (for complex work)
- [ ] **Dependencies** are identified and linked (if applicable)
- [ ] **Open questions** are flagged (if any remain)
- [ ] **Estimate** is provided (if team uses estimation)
- [ ] **No external blockers** (all prerequisites in progress or done)
### Team Readiness Check
**Before sprint starts**:
- [ ] All near-term tickets are in "Ready for Development" state
- [ ] Dependencies between tickets are clear
- [ ] Team has asked all blocking questions
- [ ] Success metrics defined for features
- [ ] Testing approach discussed for new work
## Sample Refinement Session Agenda
**Duration**: 60-90 minutes for 2-week sprint
### Timeboxed Segments
**0:00-5:00**: Opening and context
- Share sprint theme or roadmap context
- Overview of items to refine
**5:00-45:00**: Ticket refinement (30-40 minutes)
- Present each epic/feature
- Ask clarifying questions
- Discuss design, technical approach, edge cases
- Identify dependencies
- Capture open questions
**45:00-55:00**: Dependency mapping (10 minutes)
- Review identified dependencies
- Suggest parallelization opportunities
- Flag critical path
**55:00-85:00**: Estimation and prioritization (20-30 minutes)
- If using estimation, estimate tickets
- Confirm prioritization
- Ensure sprint capacity alignment
**85:00-90:00**: Wrap-up
- Recap decisions and open questions
- Assign owners for follow-ups
- Confirm next sprint readiness
## Common Refinement Issues and Solutions
| Issue | Cause | Solution |
|-------|-------|----------|
| "This is too big" | Scope creep or lack of breakdown | Suggest splitting: by layer, by user journey, by value slice |
| "We don't know how to estimate" | Missing technical details | Spike first, then estimate. Or use T-shirt sizing (S/M/L). |
| "We're blocked on [X]" | External dependency or decision needed | Create separate decision/spike ticket; mark main ticket as blocked |
| "Acceptance criteria are too vague" | Product unclear on requirements | Ask specific questions; rewrite criteria to be testable |
| "This doesn't fit in a sprint" | Ticket too large | Break into sub-tickets; move lower-priority items to next sprint |
| "We forgot about [edge case]" | Incomplete analysis | Add as acceptance criteria; may increase estimate |
## Tips for Efficient Refinement
- **Prepare ahead**: Share ticket drafts before the session so team can read
- **Time-box discussions**: Allocate time per epic/feature, move on if no progress
- **Use templates**: Consistent ticket structure speeds discussion
- **Ask not to answer**: Ask questions; don't impose solutions
- **Record decisions**: Capture what was decided, not just what was discussed
- **Assign ownership**: Each open question has an owner and due date

296
skills/product-manager/references/ticket_structure_guide.md Normal file
View File

@@ -0,0 +1,296 @@
# Ticket Structure and Best Practices
This guide defines how to structure tickets for clarity, completeness, and actionability.
## Ticket Content Standards
**Concise Content**: Maximum 500 words per ticket, ideally 150-200 words.
## Title Guidelines
- **Action-oriented**: Start with clear verbs
- **Specific**: Include what and where, not just "Fix bug" or "Add feature"
- **Under 50 characters**: Concise and scannable
- **Examples**:
- ✅ "Add CSV export for user data"
- ✅ "Fix email parser failing on non-ASCII domains"
- ❌ "Export feature"
- ❌ "Parser issue"
## Labels and Categorization
Always apply type labels for clarity:
- `Type/Feature` - New functionality
- `Type/Bug` - Defect or broken functionality
- `Type/Enhancement` - Improvement to existing feature
- `Type/Documentation` - Docs, guides, or knowledge base
- `Type/Refactor` - Code cleanup, technical debt
- `Type/Testing` - Test coverage improvements
- `Type/Infrastructure` - Deployment, CI/CD, DevOps
Additional context labels from workspace (if available):
- Priority labels (if defined): High, Medium, Low
- Platform labels: Frontend, Backend, API
- Domain labels: specific to team's structure
## Description Format
Adapt structure based on ticket complexity:
### Simple Tickets (UI changes, text updates, small fixes)
```
Brief context (1-2 sentences):
- What: What needs to change
- Where: Which component/page
- Why: Brief reason if not obvious
Example:
The "Save" button label is inconsistent with other forms.
Change "Save Draft" to "Save" on the user preferences form to match the pattern used across the dashboard.
```
### Complex Tickets (new features, workflows, API changes)
```
## Context
Why this matters (2-3 sentences, can quote user feedback):
- Problem it solves
- User impact
- Business value
## Requirements
Specific, detailed needs (bullet points):
- Functional requirements
- Non-functional requirements (performance, compatibility, etc.)
- Integration points
## Acceptance Criteria
Clear, testable conditions. For complex logic, use Given-When-Then format:
### Given-When-Then Examples:
Given a user is on the email settings page
When they select "Weekly digest"
Then the system saves the preference and shows a confirmation message
### Simple Checkboxes:
- [ ] API endpoint returns 200 status
- [ ] Response includes all required fields
- [ ] Error handling returns 400 for invalid input
## Open Questions
Flag unknowns for relevant parties (Engineering, Product, Business):
- [Engineering] How should we handle authentication for this API?
- [Product] What's the expected behavior for returning users?
- [Business] Do we need audit logging for compliance?
```
### Bug Tickets
Include reproducibility information:
```
## Steps to Reproduce
1. Navigate to email settings
2. Select a date range with special characters
3. Click "Apply"
## Expected Behavior
Settings are saved and confirmed with a message
## Actual Behavior
Page throws a 500 error
## Environment
- Browser: Chrome 120 on macOS
- Device: MacBook Pro
- OS: macOS 14.1
- Network: Stable broadband
## Severity
- Critical: Service down, data loss, security issue
- High: Core feature broken, widespread impact
- Medium: Feature partially broken, workaround exists
- Low: Minor UI issue, edge case, cosmetic
```
## Features vs Bugs
- **Features**: Focus on user need and business value
- Why does the user need this?
- What problem does it solve?
- How does it fit the product roadmap?
- **Bugs**: Focus on reproduction and impact
- Steps to reproduce (numbered, specific)
- Expected vs. actual behavior
- Environment details
- Severity and workarounds
**Prioritization**: Treat high-severity bugs like features; defer low-severity bugs.
## Acceptance Criteria Best Practices
Make acceptance criteria:
- **Testable**: Can QA or user verify without ambiguity?
- **Specific**: Includes expected data, responses, formats
- **Complete**: Covers happy path and error cases
- **Independent**: Each criterion can be verified separately
### Example: Good vs. Poor
❌ **Poor**: "User can export data"
- Too vague. Export to what format? All data or filtered? Where does the file go?
✅ **Good**:
- [ ] Export button appears in the toolbar
- [ ] Clicking export shows format options (CSV, Excel, JSON)
- [ ] Selected format exports all visible rows
- [ ] File downloads to default downloads folder
- [ ] Exported file contains all columns shown in current view
- [ ] Error handling: Shows message if no data available
## Dependency Management
Explicitly capture ticket relationships:
- **Blocks**: This ticket prevents work on another
- Use when: "Backend API must be complete before frontend can integrate"
- Example: Create endpoint (blocks) → Integrate in UI
- **Blocked By**: This ticket is waiting on another
- Use when: "Frontend work waiting on API design decision"
- Example: Integrate API (blocked by) → API design decision
- **Relates To**: Related work that should be coordinated but doesn't block
- Example: Email parser improvements (relates to) → Email formatting standards
## Estimation Guidelines
If team uses estimation:
- **Story points**: Represent relative complexity, not hours
- 1 point: Simple (UI label, small config)
- 2-3 points: Straightforward (small feature, isolated fix)
- 5-8 points: Moderate (feature with dependencies, multiple components)
- 13+ points: Large (complex feature, needs breakdown)
- **When to split**: Tickets larger than team's typical sprint velocity
- Examples: 13+ points should usually be split
## Ticket Lifecycle States
Common workflow (adapt to team's actual states):
1. **Backlog**: New, not yet reviewed
2. **Ready for Development**: Refined, detailed, dependencies clear
3. **In Progress**: Work started
4. **In Review**: Awaiting code/product review
5. **Done**: Complete and merged
## Refinement Checklist
Before marking ticket as "Ready for Development":
- [ ] Clear, action-oriented title?
- [ ] Description concise and actionable for developers?
- [ ] Appropriate labels applied?
- [ ] Dependencies identified and linked?
- [ ] Acceptance criteria present (for complex work)?
- [ ] Open questions flagged for relevant parties?
- [ ] Estimate provided (if team uses estimation)?
- [ ] No external blockers?
## Red Flags That Indicate Issues
During review, flag these as needing refinement:
- ❌ Tickets older than 90 days without updates
- ❌ Missing acceptance criteria on complex tickets
- ❌ No clear user value or "why"
- ❌ Acceptance criteria that can't be tested
- ❌ Unclear dependencies or relationships
- ❌ Multiple conflicting acceptance criteria
- ❌ Epic stories with no breakdown
- ❌ Missing error handling or edge cases
## Healthy Backlog Indicators
- Near-term items (next 2 sprints) are detailed and ready
- Long-term items (3+ months) are high-level and strategic
- Dependencies are mapped and clear
- Priorities are current and actionable
- Open questions are flagged for resolution
- No zombie tickets (unchanged for 6+ months)
- Clear epic-to-ticket hierarchy
## Technical Content Guidelines
**Default: Product-Centric Focus**
Tickets should focus on:
- User needs and business value
- Expected behavior and outcomes
- High-level architectural approach (patterns, technology choices)
- What needs to happen, not how it will be coded
- **NO code snippets or implementation details**
**Include Technical Details When:**
1. **Explicitly instructed**: User says "include X" or "make sure to note Y"
2. **Convention deviation**: Approach differs from team's standard patterns
3. **Critical constraints**: Technical limitations that affect implementation
4. **Non-standard technology**: Using different tools/libraries than usual
**Examples:**
**Default case:**
```
User request: "Create a ticket for user authentication"
✅ Good ticket:
Title: Implement user authentication
Context: Users need secure authentication to protect their accounts
Requirements:
- Secure session management
- Password reset capability
- Multi-factor authentication support
❌ Poor ticket (too implementation-heavy):
Title: Add JWT authentication
Context: Need to implement JWT with passport.js library
Code: const jwt = require('jsonwebtoken')...
```
**Explicit instruction:**
```
User request: "Create a ticket for auth, note we're using OAuth2 not JWT"
✅ Good ticket:
Title: Implement OAuth2 authentication
Context: Users need secure authentication to protect their accounts
Technical Note: Use OAuth2 instead of standard JWT pattern due to third-party integration requirements
```
**Convention deviation:**
```
User request: "We need to use MongoDB for this feature because of the dynamic schema requirements"
✅ Good ticket:
Title: Implement user preferences storage
Context: Users need ability to store custom preferences with flexible structure
Technical Note: Use MongoDB for storage (deviation from PostgreSQL standard) due to schema flexibility requirements for custom fields
```
**When to exclude code:**
❌ Don't include:
- Actual code snippets: `function authenticate(user) { ... }`
- Specific implementations: variable names, exact method signatures
- Example code from discussions
✅ Instead translate to:
- Architectural guidance: "Use Factory pattern for user creation"
- Technology choices: "Implement with WebSockets for real-time updates"
- Design constraints: "Must be stateless to support horizontal scaling"