Menu
Architecture Decision Records, API docs, inline documentation standards. Use when making architectural decisions, changing APIs, or shipping features. Document the why, not the what.
Daily research agent for
Weekly research agent for
Daily research agent for
Build, run, and secure Docker containers with current best practices. Use for Dockerfile review, multi-stage builds, Compose orchestration, image hardening, and CI/CD integration.
Operate GitHub repositories, workflows, and PRs efficiently. Use for Actions optimization, PR hygiene, repo maintenance, and team collaboration patterns.
Deploy, manage, and troubleshoot Kubernetes workloads. Use for manifest review, Helm chart validation, resource tuning, RBAC, and cluster operations.
| name | documentation-and-adrs |
| description | Architecture Decision Records, API docs, inline documentation standards. Use when making architectural decisions, changing APIs, or shipping features. Document the why, not the what. |
When this skill is invoked in Pi, treat the user's current request and any skill arguments as the task input. Do not treat this file as the task by itself.
Before applying the skill, establish only the context needed for the request:
Operate conservatively: avoid broad scans, large reads, subagents, or parallel fanout unless the user's requested depth clearly requires them.
Document architectural decisions, API contracts, and system behavior. Focus on the "why" rather than the "what" because code already tells you what happens. Documentation should explain why it was designed that way.
Record significant architectural decisions:
Save as: docs/decisions/{YYYY-MM-DD}-{title}.md
Document public APIs with:
Every project should have:
| Rationalization | Reality |
|---|---|
| "The code is self-documenting" | Code tells you what. Documentation tells you why. Both are needed. |
| "Documentation goes stale immediately" | Stale docs are a signal to update, not to stop documenting. |
| "I will document later" | Later never comes. Document alongside the implementation. |
| Excuse | Counter |
|---|---|
| "The code is self-documenting" | Code tells you what. Documentation tells you why. Both are needed. |
| "Documentation goes stale immediately" | Stale docs are a signal to update, not to stop documenting. |
| "I'll document later" | Later never comes. Document alongside the implementation. |
| "ADRs are too formal for this decision" | Even small decisions benefit from recorded rationale. Future you will thank present you. |
| "No one reads documentation" | People read docs when they are stuck. Good docs prevent being stuck. |
