prulloac/feature-summary

Feature Summary Skill

Answers the question: How do we DOCUMENT and COMMUNICATE a feature to stakeholders, users, and developers?

This skill focuses on feature documentation and communication, transforming detailed breakdowns into accessible, comprehensive summaries that serve multiple audiences.

When to Use

Use this skill when you have a completed feature (or a detailed feature breakdown) and need to:

• Create comprehensive user-facing documentation
• Build a feature catalog or knowledge base
• Document business features for stakeholder communication
• Explain technical implementation to developers
• Create feature roadmaps and status tracking
• Document current and future capabilities
• Classify features by type (core, customization, performance, accessibility, UX)

Key indicator: You're asking "How do we document and communicate this feature?" or "What should users know about this capability?"

Works best with: This skill complements feature-breakdown (provides the detailed task list) and feature-planning (provides the execution sequence)

When NOT to Use

• You only have a feature idea/spec without breakdown details → Use feature-breakdown first
• You need to determine task execution order → Use feature-planning instead
• You need to track real-time implementation progress → Use execution-tracking instead

Prerequisites

Recommended (but not strictly required):

1. Feature breakdown (docs/features/[feature-name]/breakdown.md)

   • Provides detailed task list and component architecture
   • Helps identify all feature aspects to document

2. Feature implementation (completed or well-understood)

   • Access to working code or specifications
   • Understanding of current status

3. Audience understanding

   • Who will read this documentation?
   • What do they need to know?

Inputs

• Feature specification or implemented feature (required)
• Feature breakdown document (recommended): docs/features/[feature-name]/breakdown.md
• Source code access (optional but helpful): For accurate implementation details
• Usage examples (optional): For user documentation

Directory Structure

All feature-summary output must follow this structure:

docs/features/[feature-name]/
├── breakdown.md              (created by feature-breakdown skill)
├── summary.md                (created by this skill - PRIMARY OUTPUT)
├── configuration.md          (optional - created by this skill)
├── reference.md              (optional - created by this skill)
└── implementation-progress.md (created by execution-tracking skill during implementation)

Outputs

MANDATORY FILE ORGANIZATION: All feature documentation must be in docs/features/<feature-name>/ subdirectory.

When this skill completes, it creates:

1. Primary Output: Feature Summary (docs/features/[feature-name]/summary.md)

   • Comprehensive feature documentation
   • 150-250 lines covering all major aspects
   • Serves multiple audiences (users, developers, stakeholders)
   • Includes feature type classification
   • Example: docs/features/git-blame-overlay/summary.md

2. Optional: Configuration Reference (docs/features/[feature-name]/configuration.md)

   • Detailed configuration options and examples
   • For features with significant customization

3. Optional: Reference Guide (docs/features/[feature-name]/reference.md)

   • Technical implementation details for developers
   • Architecture decisions and patterns

4. Supporting Structure:

   • docs/features/[feature-name]/breakdown.md - Implementation tasks (created by feature-breakdown skill)
   • docs/features/[feature-name]/implementation-progress.md - Tracking file (created by execution-tracking skill)

Workflow Overview

The feature summary process transforms a feature concept into comprehensive documentation:

Feature Input (Breakdown or Implementation)
    ↓
Analyze Feature Aspects
    ↓
Identify Audiences & Use Cases
    ↓
Classify Feature Type
    ↓
Create Executive Summary
    ↓
Document Configuration & Options
    ↓
Explain Technical Implementation
    ↓
Define Status & Version Info
    ↓
Identify Limitations & Future Enhancements
    ↓
Write Output Files
    ↓
Comprehensive Feature Documentation

Core Workflow

Phase 1: Analyze Feature Scope

Input: Feature specification, breakdown, or implementation

1. Identify feature aspects:

   • What does it do? (Core functionality)
   • Why is it valuable? (Business value)
   • How do users interact with it? (User experience)
   • What are the key capabilities? (Feature list)
   • What are the limitations? (Edge cases and constraints)

2. Extract technical details:

   • How is it implemented? (Architecture, components)
   • What are the technical requirements? (Dependencies, prerequisites)
   • Where is the code located? (Source file references)
   • What patterns or technologies are used?

3. Understand current state:

   • Version number and release status
   • When was it introduced?
   • What improvements or fixes have been made?
   • Is it production-ready?

Phase 2: Classify Feature Type

Assign the feature to one or more categories:

| Category | Description | Examples | |----------|-------------|----------| | Core Functionality | Essential feature defining the product's primary purpose | Git blame overlay, authentication system | | Customization | Allows users to personalize behavior and appearance | Output patterns, color customization | | User Experience | Improves usability, visual integration, and workflow | Theme adaptation, command palette | | Accessibility | Supports users with different abilities and needs | Color options, keyboard shortcuts, ARIA labels | | Performance | Optimizes speed and resource usage | Caching, lazy loading, pagination | | Extended Functionality | Non-essential features that enhance core capability | Advanced filtering, export options | | Developer Experience | Improves developer productivity and experience | Debugging tools, API documentation |

Output Format

Feature summaries include these key sections (in order):

1. Feature Header - Name, overview, status, version, feature type
2. Business Value - Why it matters, specific benefits
3. What It Does - Core functionality with user experience and examples
4. Key Features - Capabilities and extended functionality
5. Configuration (if applicable) - Options and examples
6. Technical Implementation - Code references and architecture
7. User Interactions - Workflows and commands
8. Status and Roadmap - Current status, limitations, future enhancements
9. Related Features - Cross-references to related features

For a complete template with examples and detailed guidelines, see:

• assets/documentation-template.md - Blank template for creating new features
• examples/example-feature-summary-core.md - Core functionality example
• examples/example-feature-summary-customization.md - Customization example
• examples/example-feature-summary-performance.md - Performance example

Feature Type Classification

Every feature should be classified with a primary type and optional secondary types. This helps users understand:

• What is this feature? (Its purpose)
• Is it essential? (Core vs. optional)
• How does it relate to other features? (Ecosystem awareness)

Quick Reference

| Type | Icon | Purpose | Example | |------|------|---------|---------| | Core Functionality | ⭐ | Essential, defines product purpose | Git blame overlay | | Customization | 🎨 | Personalization & preferences | Output patterns | | User Experience | 👥 | Usability & visual integration | Theme-aware styling | | Accessibility | ♿ | Support for diverse users | Color options | | Performance | 🚀 | Speed & resource optimization | Caching system | | Extended Functionality | ➕ | Optional enhancements | Export options | | Developer Experience | 🛠️ | Developer productivity | API docs |

For detailed guidance on each type, see references/feature-type-reference.md

Guidelines

Writing for Multiple Audiences

For Users:

• Use clear, non-technical language
• Explain benefits and use cases
• Provide concrete examples
• Include configuration examples

For Developers:

• Include code references and file paths
• Explain architecture and design decisions
• Document patterns and conventions
• Link to technical documentation

For Stakeholders:

• Lead with business value
• Emphasize impact and ROI
• Focus on status and roadmap
• Quantify benefits where possible

Feature Classification

When assigning feature types:

1. Identify primary category: What is this feature's main purpose?
2. Note secondary categories: Can it serve multiple purposes?
3. Explain classification: Why does this categorization make sense?
4. Consider user perception: How do users think about this feature?

Technical Accuracy

• Reference actual source code paths
• Include line numbers for specific implementations
• Verify all code examples work correctly
• Document technical constraints accurately

Keeping Documentation Current

• Update status section when feature versions change
• Add to limitations if new constraints are discovered
• Move items from "Future Enhancements" when implemented
• Update configuration examples if options change

Common Pitfalls to Avoid

❌ Too technical for users: Remember non-technical readers; explain technical concepts ❌ Too vague for developers: Provide specific code references and implementation details ❌ Incomplete feature classification: Always explain why a feature fits its category ❌ Missing examples: Concrete examples are crucial for understanding ❌ Outdated information: Keep status and version info current ❌ Poor cross-linking: Reference related features; help readers understand relationships ❌ Missing technical details: Developers need code references and architecture info

Integration with Other Skills

The feature-summary skill works as part of a larger feature documentation ecosystem. For detailed integration workflows and examples:

• Overview of the skill ecosystem: references/ecosystem-diagram.md
• Practical integration workflows: references/workflow-integration-guide.md
• Quick navigation: references/integration-guide.md

Recommended Skill Sequence

1. feature-breakdown (1-2 hrs) - Decompose feature into tasks and acceptance criteria
2. feature-summary (1-2 hrs) - Create user-facing documentation
3. feature-planning (1-2 hrs) - Sequence tasks for execution
4. execution-tracking (ongoing) - Monitor implementation progress

Key Concepts

feature-breakdown creates (docs/features/[name]/breakdown.md):

• Internal task list
• Component architecture
• Acceptance criteria
• Validation plan

feature-summary creates (docs/features/[name]/summary.md):

• User-facing documentation
• Business value explanation
• Configuration examples
• Roadmap and future enhancements

Quality Checklist

Before finalizing feature documentation:

• [ ] Feature type classification is clear and explained
• [ ] Business value section explains "why" not just "what"
• [ ] Examples show real-world usage
• [ ] Technical details are accurate with code references
• [ ] Configuration options are clearly documented
• [ ] Status and version info are current
• [ ] Known limitations are honestly documented
• [ ] Future enhancements are realistic and categorized
• [ ] Cross-references to related features are accurate
• [ ] Documentation is accessible to intended audiences
• [ ] Language is clear and concise
• [ ] All file paths and code references are accurate

Example Output

For a real example of how feature documentation should look, see the example feature summaries:

• Reference: examples/example-feature-summary-core.md (Core functionality example)
• Reference: examples/example-feature-summary-customization.md (Customization example)
• Reference: examples/example-feature-summary-performance.md (Performance feature example)

See Also

• feature-breakdown - Decompose features into tasks
• feature-planning - Sequence tasks for execution
• execution-tracking - Monitor feature implementation progress
• readme-updater - Keep project README in sync with features