opencode-metis 0.1.0

package/opencode/skill/technical-writing/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: technical-writing
+description: "Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks. Use when capturing design decisions, documenting system architecture, creating API references, or writing operational procedures."
+license: MIT
+compatibility: opencode
+metadata:
+  category: development
+  version: "1.0"
+---
+
+# Technical Writing
+
+Roleplay as a technical writing specialist that creates ADRs, system documentation, API references, and operational runbooks that preserve knowledge and enable informed decision-making.
+
+TechnicalWriting {
+  Activation {
+    Recording architectural or design decisions with context and rationale
+    Documenting system architecture for new team members or stakeholders
+    Creating API documentation for internal or external consumers
+    Writing runbooks for operational procedures and incident response
+    Capturing tribal knowledge before it's lost to team changes
+  }
+
+  DocumentationTypes {
+    ArchitectureDecisionRecords {
+      Purpose => Capture context, options considered, and rationale behind significant architectural decisions
+      Value => Historical record that helps future developers understand why the system is built a certain way
+
+      WhenToCreate {
+        Choosing between different technologies, frameworks, or approaches
+        Making decisions that are difficult or expensive to reverse
+        Establishing patterns that will be followed across the codebase
+        Deprecating existing approaches in favor of new ones
+        Any decision that a future developer might question
+      }
+
+      Template => See [adr-template.md](templates/adr-template.md)
+    }
+
+    SystemDocumentation {
+      Purpose => Comprehensive view of how a system works, its components, and their relationships
+      Value => Helps new team members onboard and serves as a reference for operations
+
+      KeyElements {
+        System overview and purpose
+        Architecture diagrams showing component relationships
+        Data flows and integration points
+        Deployment architecture
+        Operational requirements
+      }
+
+      Template => See [system-doc-template.md](templates/system-doc-template.md)
+    }
+
+    APIDocumentation {
+      Purpose => Describes how to interact with a service
+
+      KeyElements {
+        Authentication and authorization
+        Endpoint reference with examples
+        Request and response schemas
+        Error codes and handling
+        Rate limits and quotas
+        Versioning strategy
+      }
+    }
+
+    Runbooks {
+      Purpose => Step-by-step procedures for operational tasks, from routine maintenance to incident response
+
+      KeyElements {
+        Pre-requisites and access requirements
+        Step-by-step procedures with expected outcomes
+        Troubleshooting common issues
+        Escalation paths
+        Recovery procedures
+      }
+    }
+  }
+
+  DocumentationPatterns {
+    DecisionContextFirst {
+      Rule => Always document the context and constraints that led to a decision before stating the decision itself
+      Why => Future readers need to understand the "why" before the "what"
+
+      Example {
+        ```markdown
+        ## Context
+
+        We need to store user session data that must be:
+        - Available across multiple application instances
+        - Retrieved in under 10ms
+        - Retained for 24 hours after last activity
+
+        Our current database is PostgreSQL, which would require additional
+        infrastructure for session management.
+
+        ## Decision
+
+        We will use Redis for session storage.
+        ```
+      }
+    }
+
+    LivingDocumentation {
+      Rule => Documentation should be updated as part of the development process, not as an afterthought
+      Integration => Include documentation updates in definition of done
+
+      Practices {
+        Update ADRs when decisions change (mark old ones as superseded)
+        Revise system docs when architecture evolves
+        Keep API docs in sync with implementation (prefer generated docs where possible)
+        Review runbooks after each incident for accuracy
+      }
+    }
+
+    AudienceAppropriateDetail {
+      Rule => Tailor documentation depth to its intended audience
+
+      | Audience | Focus | Detail Level |
+      |----------|-------|--------------|
+      | New developers | Onboarding, getting started | High-level concepts, step-by-step guides |
+      | Experienced team | Reference, troubleshooting | Technical details, edge cases |
+      | Operations | Deployment, monitoring | Procedures, commands, expected outputs |
+      | Business stakeholders | Capabilities, limitations | Non-technical summaries, diagrams |
+    }
+
+    DiagramsOverProse {
+      Rule => Use diagrams to communicate complex relationships
+      Why => A well-designed diagram can replace pages of text and is easier to maintain
+
+      RecommendedDiagramTypes {
+        SystemContext => Shows system boundaries and external interactions
+        Container => Shows major components and their relationships
+        Sequence => Shows how components interact for specific flows
+        DataFlow => Shows how data moves through the system
+      }
+    }
+
+    ExecutableDocumentation {
+      Rule => Where possible, make documentation executable or verifiable
+
+      Examples {
+        API examples that can be run against a test environment
+        Code snippets that are extracted from actual tested code
+        Configuration examples that are validated in CI
+        Runbook steps that have been recently executed
+      }
+    }
+  }
+
+  ADRLifecycle {
+    States {
+      Proposed => Decision is being discussed, not yet accepted
+      Accepted => Decision has been made and should be followed
+      Deprecated => Decision is being phased out, new work should not follow it
+      Superseded => Decision has been replaced by a newer ADR (link to new one)
+    }
+
+    SupersedingProcess {
+      1. Add "Superseded by ADR-XXX" to the old record
+      2. Add "Supersedes ADR-YYY" to the new record
+      3. Explain what changed and why in the new ADR's context
+    }
+  }
+
+  BestPractices {
+    Write documentation close to the code it describes (prefer docs-as-code)
+    Use templates consistently to make documentation predictable
+    Include diagrams for architecture; text for procedures
+    Date all documents and note last review date
+    Keep ADRs immutable once accepted (create new ones to supersede)
+    Store documentation in version control alongside code
+    Review documentation accuracy during code reviews
+    Delete or archive documentation for removed features
+  }
+
+  AntiPatterns {
+    DocumentationDrift => Docs that no longer match reality are worse than no docs
+    OverDocumentation => Documenting obvious code reduces signal-to-noise
+    WikiSprawl => Documentation scattered across multiple systems becomes unfindable
+    FutureFiction => Documenting features that don't exist yet as if they do
+    WriteOnlyDocs => Creating docs that no one reads or maintains
+  }
+}
+
+## References
+
+- [adr-template.md](templates/adr-template.md) - Architecture Decision Record template
+- [system-doc-template.md](templates/system-doc-template.md) - System documentation template

package/opencode/skill/technical-writing/templates/adr-template.md

@@ -0,0 +1,205 @@
+# Template: Architecture Decision Record (ADR)
+
+## Purpose
+
+Use this template to document significant architectural and design decisions. ADRs capture the context, options considered, and rationale behind decisions that are:
+
+- Difficult or expensive to reverse
+- Foundational to how the system works
+- Likely to be questioned by future developers
+- Establishing patterns for the codebase
+
+## Template
+
+```markdown
+# ADR-[NUMBER]: [SHORT TITLE]
+
+**Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+**Date:** [YYYY-MM-DD when decision was made]
+**Decision Makers:** [Names or roles involved in the decision]
+
+## Context
+
+[Describe the situation that requires a decision. Include:]
+
+- What problem are you solving?
+- What constraints exist (technical, business, timeline)?
+- What assumptions are you making?
+- What is the current state of the system?
+
+[Be specific enough that someone unfamiliar with the project can understand
+the situation. Avoid jargon without explanation.]
+
+## Decision Drivers
+
+[List the key factors that will influence this decision:]
+
+- [Driver 1: e.g., "Must support 10,000 concurrent users"]
+- [Driver 2: e.g., "Team has limited experience with NoSQL databases"]
+- [Driver 3: e.g., "Budget constraints limit managed service options"]
+
+## Options Considered
+
+### Option 1: [Name]
+
+[Brief description of this option]
+
+**Pros:**
+- [Advantage 1]
+- [Advantage 2]
+
+**Cons:**
+- [Disadvantage 1]
+- [Disadvantage 2]
+
+### Option 2: [Name]
+
+[Brief description of this option]
+
+**Pros:**
+- [Advantage 1]
+- [Advantage 2]
+
+**Cons:**
+- [Disadvantage 1]
+- [Disadvantage 2]
+
+### Option 3: [Name]
+
+[Brief description of this option]
+
+**Pros:**
+- [Advantage 1]
+- [Advantage 2]
+
+**Cons:**
+- [Disadvantage 1]
+- [Disadvantage 2]
+
+## Decision
+
+[State the decision clearly and unambiguously.]
+
+We will use **[Option X]** because [primary reason].
+
+## Rationale
+
+[Explain why this option was chosen over the alternatives:]
+
+- How does it address the decision drivers?
+- What trade-offs are being made?
+- Why were other options rejected?
+
+[This section should help future readers understand the thinking process,
+not just the outcome.]
+
+## Consequences
+
+### Positive
+
+- [Benefit 1 this decision enables]
+- [Benefit 2 this decision enables]
+
+### Negative
+
+- [Drawback 1 we are accepting]
+- [Drawback 2 we are accepting]
+
+### Neutral
+
+- [Side effect that is neither clearly positive nor negative]
+
+## Implementation Notes
+
+[Optional: Include any specific guidance for implementing this decision:]
+
+- Migration path from current state
+- Key technical details
+- Dependencies or prerequisites
+- Estimated effort
+
+## Related Decisions
+
+- [ADR-XXX: Related decision about Y]
+- [ADR-YYY: This decision supersedes/is superseded by]
+
+## References
+
+- [Link to relevant documentation, research, or discussions]
+- [Link to spike or proof-of-concept if applicable]
+```
+
+## Usage Instructions
+
+1. Copy the template above into a new file named `ADR-[NUMBER]-[slug].md`
+2. Number ADRs sequentially (ADR-001, ADR-002, etc.)
+3. Fill in the status as "Proposed" during discussion
+4. Update status to "Accepted" when decision is finalized
+5. Never edit accepted ADRs; create new ones that supersede them
+6. Store ADRs in a `docs/decisions/` or `docs/adr/` directory
+
+## Numbering Convention
+
+Use zero-padded sequential numbers:
+- `ADR-001-use-postgresql-for-persistence.md`
+- `ADR-002-adopt-event-sourcing-pattern.md`
+- `ADR-003-migrate-to-kubernetes.md`
+
+## Status Transitions
+
+```
+Proposed --> Accepted --> Deprecated
+                     --> Superseded by ADR-XXX
+```
+
+- **Proposed**: Under discussion, not yet binding
+- **Accepted**: Decision is made and should be followed
+- **Deprecated**: Being phased out, do not use for new work
+- **Superseded**: Replaced by a newer ADR (always link to it)
+
+## Examples
+
+### Good ADR Title
+- "Use PostgreSQL for primary data storage"
+- "Adopt event-driven architecture for order processing"
+- "Implement feature flags using LaunchDarkly"
+
+### Poor ADR Title
+- "Database decision" (too vague)
+- "We should use PostgreSQL because it's better" (includes rationale in title)
+- "ADR about the thing we discussed" (not descriptive)
+
+### Good Context Section
+
+```markdown
+## Context
+
+Our application currently stores all data in a single MySQL 5.7 database
+hosted on AWS RDS. We are experiencing:
+
+- Query latency exceeding 500ms for reporting queries
+- Lock contention during high-write periods (daily imports)
+- Storage costs increasing 20% month-over-month
+
+The team has been asked to reduce p95 latency to under 100ms while
+supporting 3x current data volume within 6 months. Our team has
+production experience with PostgreSQL and limited experience with
+NoSQL databases.
+```
+
+### Poor Context Section
+
+```markdown
+## Context
+
+We need a better database because the current one is slow.
+```
+
+## Tips for Effective ADRs
+
+1. **Write for future readers**: Assume the reader has no context about your project
+2. **Be honest about trade-offs**: Every decision has downsides; document them
+3. **Include rejected options**: Understanding why alternatives were rejected is valuable
+4. **Keep it concise**: ADRs should be readable in 5-10 minutes
+5. **Link to evidence**: Reference benchmarks, spikes, or discussions that informed the decision
+6. **Date your decisions**: Context changes; knowing when a decision was made matters