Documentation

Write effective user stories that capture requirements from the user's perspective. Create clear stories with detailed acceptance criteria to guide development and define done.

Gate 3: Technical architecture document - defines HOW/WHERE with technology-agnostic patterns before concrete implementation choices.

Create comprehensive technical roadmaps aligned with business goals. Plan technology investments, architecture evolution, and infrastructure improvements over quarters and years.

Write comprehensive code documentation including JSDoc, Python docstrings, inline comments, function documentation, and API comments. Use when documenting code, writing docstrings, or creating inline documentation.

Development cycle feedback system - calculates assertiveness scores, analyzes prompt quality for all agents executed, aggregates cycle metrics, performs root cause analysis on failures, and generates improvement reports to docs/feedbacks/cycle-{date}/.

Analyze code complexity, cyclomatic complexity, maintainability index, and code churn using metrics tools. Use when assessing code quality, identifying refactoring candidates, or monitoring technical debt.

Create comprehensive developer onboarding documentation including setup guides, README files, contributing guidelines, and getting started tutorials. Use when onboarding new developers or creating setup documentation.

Document deployment processes, infrastructure setup, CI/CD pipelines, and configuration management. Use when creating deployment guides, infrastructure docs, or CI/CD documentation.

Creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps for engineers with zero codebase context.

Transform raw brain dumps (dictated freestyle) into structured implementation artifacts. Use when user has messy ideas, scattered thoughts, or dictated stream-of-consciousness about something they want to build. Produces contracts, phased PRDs, and implementation specs written to ./docs/ideation/{project-name}/.

Master markdown formatting, GitHub Flavored Markdown, README files, and documentation formatting. Use when writing markdown docs, READMEs, or formatting documentation.

Create system architecture diagrams using Mermaid, PlantUML, C4 model, flowcharts, and sequence diagrams. Use when documenting architecture, system design, data flows, or technical workflows.

name: octave-compression

This skill should be used when editing Python code in the erk codebase. Use when writing, reviewing, or refactoring Python to ensure adherence to LBYL exception handling patterns, Python 3.13+ type syntax (list[str], str | None), pathlib operations, ABC-based interfaces, absolute imports, and explicit error boundaries at CLI level. Also provides production-tested code smell patterns from Dagster Labs for API design, parameter complexity, and code organization. Essential for maintaining erk's dignified Python standards.

Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.

Create comprehensive user guides, tutorials, how-to documentation, and step-by-step instructions with screenshots and examples. Use when writing user documentation, tutorials, or getting started guides.

Structured workflow for onboarding new services to the internal platform including infrastructure provisioning, observability setup, and documentation.

Patterns and structure for writing functional documentation including guides, conceptual explanations, tutorials, and best practices documentation.

Voice and tone guidelines for technical documentation. Ensures consistent, clear, and human writing across all documentation.

Interview user in-depth about a spec, bead, or feature idea to extract complete implementation details. Use when user wants to flesh out a spec, refine requirements, discuss technical details, clarify a feature before building, or asks to be interviewed about their idea. Triggers on "interview me", "ask me questions about", "flesh out this spec", "refine requirements", "help me think through".