@mohammadhprp/system-prompt 0.10.1

package/framework/plugins/opencode-goal-plugin/troubleshooting.md

@@ -0,0 +1,112 @@
+# OpenCode Goal Plugin Troubleshooting
+
+## Plugin not recognized
+
+**Problem**
+
+`opencode plugin @prevalentware/opencode-goal-plugin` returns an error.
+
+**Cause**
+
+The package name is incorrect, or OpenCode cannot reach the npm registry.
+
+**Solution**
+
+- Verify the package name: `@prevalentware/opencode-goal-plugin`.
+- Check network connectivity to the npm registry.
+- Ensure OpenCode >= 1.17.1 is installed: `opencode --version`.
+
+## Manual config needed
+
+**Problem**
+
+The plugin is installed but does not appear in OpenCode.
+
+**Cause**
+
+The CLI install may not write to all config targets on some platforms.
+
+**Solution**
+
+- Add the plugin to `opencode.json`: `"plugin": ["@prevalentware/opencode-goal-plugin"]`.
+- Add the plugin to `tui.json`: `"plugin": ["@prevalentware/opencode-goal-plugin"]`.
+- Restart OpenCode.
+
+## Goal not persisting
+
+**Problem**
+
+The goal disappears after session compaction or restart.
+
+**Cause**
+
+The state file cannot be written, or the filesystem does not support atomic writes.
+
+**Solution**
+
+- Check that the state file path is writable: `$XDG_DATA_HOME/opencode-goal-plugin/goals.json` (defaults to `~/.local/share/opencode-goal-plugin/goals.json`).
+- Set `OPENCODE_GOAL_STATE_PATH` to a custom writable path.
+- Verify disk space is available.
+
+## Auto-continue not working
+
+**Problem**
+
+The goal is set but the agent does not auto-continue on idle.
+
+**Cause**
+
+`auto_continue` is disabled, or the goal is paused or closed.
+
+**Solution**
+
+- Check `auto_continue` is `true` in the plugin options.
+- Verify the goal status is `active` with `/goal`.
+- Check that no-progress detection has not paused the goal.
+- Verify the session is in Build mode (Plan mode suppresses auto-continue).
+
+## Plan mode restrictions
+
+**Problem**
+
+Goals created from Plan mode are paused immediately.
+
+**Cause**
+
+By default, `restricted_agents` includes `"plan"`, and Plan-mode goals start paused.
+
+**Solution**
+
+- Switch to Build mode and run `/goal resume` to activate the goal.
+- To disable this restriction, set `allow_goal_execution_from_plan: true` in the plugin options (not recommended).
+
+## Goal closed prematurely
+
+**Problem**
+
+The goal was marked complete or unmet without sufficient evidence.
+
+**Cause**
+
+The agent closed the goal without verifying all requirements.
+
+**Solution**
+
+- Use `/goal history` to review how the goal was closed.
+- Use `/goal edit <updated objective>` and `/goal resume` to restart with clearer criteria.
+- Include specific verification steps in the original objective.
+
+## State file permission errors
+
+**Problem**
+
+The plugin logs permission errors when writing goal state.
+
+**Cause**
+
+The state file has restrictive permissions from a previous owner or process.
+
+**Solution**
+
+- Remove the state file: `rm ~/.local/share/opencode-goal-plugin/goals.json`.
+- Ensure the OpenCode process has write access to the parent directory.

package/framework/plugins/ponytail/README.md

@@ -0,0 +1,44 @@
+# Ponytail Plugin
+
+## Overview
+
+Ponytail makes your AI agent think like the laziest senior dev in the room. Before writing code, the agent climbs a ladder of checks: YAGNI first, then reuse what exists, reach for stdlib, native features, installed deps, one-liners, and only then the minimum code that works. The result is less code, lower cost, and faster sessions without cutting safety.
+
+Official source:
+
+- [GitHub: DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
+- [npm: @dietrichgebert/ponytail](https://www.npmjs.com/package/@dietrichgebert/ponytail)
+
+## Features
+
+- **Lazy senior dev ladder**: seven-rung decision tree the agent climbs before writing code.
+- **Slash commands**: `/ponytail [lite|full|ultra|off]`, `/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`, `/ponytail-gain`, `/ponytail-help`.
+- **Mode switching**: four intensity levels (off, lite, full, ultra) persisted across sessions.
+- **Bundled skills**: review, audit, debt, gain, and help skills included.
+- **Always-on injection**: ruleset appended to the system prompt every turn.
+- **Agent-portable**: works with 16+ agent platforms via rules files, AGENTS.md, or plugins.
+
+## When to Use
+
+Use this plugin in any coding session where the agent tends to over-engineer, write unnecessary abstractions, or reach for dependencies instead of simpler solutions.
+
+Good fits:
+- Reducing code bloat and unnecessary complexity.
+- Lowering token usage and API costs.
+- Enforcing YAGNI and reuse-first discipline.
+- Reviewing diffs for over-engineering.
+
+Avoid when the task explicitly needs complex scaffolding, heavy abstractions, or framework boilerplate.
+
+## Requirements
+
+- OpenCode >= 1.17.0 (for plugin loading).
+- Node.js on PATH (for lifecycle hooks).
+
+## Related Skills
+
+Relevant skills in this repository:
+
+- [`code-review`](../../skills/code-review/SKILL.md): review backend changes for correctness and maintainability, complementary to ponytail's over-engineering focus.
+- [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for refactoring and behavior-preserving cleanup.
+- [`pull-request`](../../skills/pull-request/SKILL.md): prepare small, reviewable changes aligned with ponytail's minimal-diff philosophy.

package/framework/plugins/ponytail/capabilities.md

@@ -0,0 +1,112 @@
+# Ponytail Plugin Capabilities
+
+## What It Can Do
+
+### Slash Commands
+
+| Command | Description |
+|---|---|
+| `/ponytail` | Report the current mode |
+| `/ponytail lite` | Set lightweight mode (gentle nudge) |
+| `/ponytail full` | Set full mode (default, standard lazy senior dev) |
+| `/ponytail ultra` | Set ultra mode (aggressive minimalism) |
+| `/ponytail off` | Disable ponytail |
+| `/ponytail-review` | Review the current diff for over-engineering, returns a delete-list |
+| `/ponytail-audit` | Audit the whole repo for over-engineering |
+| `/ponytail-debt` | Harvest deferred `ponytail:` shortcuts into a ledger |
+| `/ponytail-gain` | Show measured impact scoreboard (less code, cost, speed) |
+| `/ponytail-help` | Quick reference for all ponytail commands |
+
+### Bundled Skills
+
+- `ponytail` — core lazy senior dev mode
+- `ponytail-review` — diff review for over-engineering
+- `ponytail-audit` — full repo audit for over-engineering
+- `ponytail-debt` — technical debt tracking for shortcuts
+- `ponytail-gain` — impact measurement
+- `ponytail-help` — command reference
+
+### The Ladder (Core Ruleset)
+
+Before writing code, the agent stops at the first rung that holds:
+
+1. **Does this need to exist?** → no: skip it (YAGNI)
+2. **Already in this codebase?** → reuse it, don't rewrite
+3. **Stdlib does it?** → use it
+4. **Native platform feature?** → use it
+5. **Installed dependency?** → use it
+6. **One line?** → one line
+7. **Only then**: the minimum that works
+
+The ladder runs after the agent understands the problem — it reads the code it touches and traces the real flow before picking a rung.
+
+### System Prompt Transformation
+
+The plugin appends the ruleset to the system prompt every turn, so the ladder is always active. Mode switches are persisted between sessions via a state file.
+
+## Configuration Options
+
+Configure in `opencode.json`:
+
+```json
+{
+  "plugin": ["@dietrichgebert/ponytail"]
+}
+```
+
+Set the default mode via environment variable:
+
+```bash
+export PONYTAIL_DEFAULT_MODE=full
+```
+
+Or in `~/.config/ponytail/config.json` (`%APPDATA%\ponytail\config.json` on Windows):
+
+```json
+{
+  "defaultMode": "full"
+}
+```
+
+### Mode Levels
+
+| Mode | Description |
+|---|---|
+| `off` | Disabled, no rules injected |
+| `lite` | Gentle nudge toward simplicity |
+| `full` | (Default) Standard lazy senior dev rules |
+| `ultra` | Aggressive minimalism |
+
+## What It Cannot Do
+
+- It cannot override explicit user requests for complex implementations.
+- It cannot guarantee correctness — it minimizes code, but validation and error handling are never cut.
+- It cannot enforce YAGNI on dependencies already installed and used by the project.
+- It cannot prevent the agent from building what was explicitly requested.
+
+## Best Practices
+
+- Start with `full` mode and adjust to `ultra` if the codebase needs aggressive simplification.
+- Use `/ponytail-review` after a coding session to catch over-engineering the agent missed.
+- Mark intentional shortcuts with `ponytail:` comments naming the ceiling and upgrade path.
+- Review `/ponytail-debt` regularly to track deferred improvements.
+- Pair with `code-review` and `pull-request` skills for a complete quality workflow.
+
+## Common Workflows
+
+### Start a session with ponytail
+
+1. Install the plugin and start OpenCode.
+2. Run `/ponytail` to confirm the mode (defaults to `full`).
+3. Work as usual — the ruleset is active every turn.
+
+### Review a diff
+
+1. After making changes, run `/ponytail-review`.
+2. Review the delete-list and remove unnecessary code.
+
+### Switch mode mid-session
+
+1. Run `/ponytail ultra` to go aggressive.
+2. Run `/ponytail off` to disable temporarily.
+3. The mode persists across session restarts.

package/framework/plugins/ponytail/install.md

@@ -0,0 +1,77 @@
+# Ponytail Plugin Installation
+
+## Requirements
+
+- OpenCode >= 1.17.0 installed.
+- Node.js on PATH (required by lifecycle hooks; Nix/nvm users must have it on the non-interactive shell's PATH).
+
+## Installation
+
+### OpenCode
+
+Add to `opencode.json`:
+
+```json
+{
+  "plugin": ["@dietrichgebert/ponytail"]
+}
+```
+
+Or install from a local checkout (reuses `hooks/` and `skills/`):
+
+```json
+{
+  "plugin": ["./.opencode/plugins/ponytail.mjs"]
+}
+```
+
+The `./` path resolves against your project's `opencode.json`. To share one checkout across projects, point it at the absolute path of the `.mjs` instead.
+
+### Other Platforms
+
+The plugin works with 16+ agent platforms. See the [official install guide](https://github.com/DietrichGebert/ponytail#install) for platform-specific instructions.
+
+| Platform | Command |
+|---|---|
+| Claude Code | `/plugin marketplace add DietrichGebert/ponytail` then `/plugin install ponytail@ponytail` |
+| Codex | `codex plugin marketplace add DietrichGebert/ponytail` |
+| Copilot CLI | `copilot plugin marketplace add DietrichGebert/ponytail` |
+| Gemini CLI | `gemini extensions install https://github.com/DietrichGebert/ponytail` |
+| Pi agent | `pi install git:github.com/DietrichGebert/ponytail` |
+| Hermes | `hermes plugins install DietrichGebert/ponytail --enable` |
+
+## Verification
+
+After installing, start or restart OpenCode and run:
+
+```
+/ponytail
+```
+
+You should see the current mode. The ruleset activates every turn.
+
+## Updating
+
+```bash
+opencode plugin update @dietrichgebert/ponytail
+```
+
+## Uninstalling
+
+Remove the plugin entry from `opencode.json`. On other platforms:
+
+| Platform | Command |
+|---|---|
+| Claude Code | `/plugin remove ponytail` |
+| Codex | `codex plugin remove ponytail` |
+| Devin CLI | `devin plugins remove ponytail` |
+| Pi agent | `pi uninstall ponytail` |
+
+To clean up state files, run `node scripts/uninstall.js` from a clone of the repo before removing the plugin.
+
+## Common Issues
+
+- **Plugin not loaded**: ensure `@dietrichgebert/ponytail` is in the `plugin` array in `opencode.json`.
+- **Node.js not found**: lifecycle hooks need Node.js on PATH. Verify with `node --version`.
+- **Mode not persisting**: mode state is stored in `~/.config/opencode/.ponytail-active`. Check that the directory is writable.
+- **Rules not applying**: the plugin injects rules via the system prompt transform. Verify the plugin is active with `/ponytail`.

package/framework/plugins/ponytail/troubleshooting.md

@@ -0,0 +1,116 @@
+# Ponytail Plugin Troubleshooting
+
+## Plugin not recognized
+
+**Problem**
+
+OpenCode does not load the ponytail plugin.
+
+**Cause**
+
+The plugin name is incorrect or OpenCode cannot resolve the npm package.
+
+**Solution**
+
+- Verify the package name: `@dietrichgebert/ponytail`.
+- Check network connectivity to the npm registry.
+- Ensure OpenCode >= 1.17.0 is installed: `opencode --version`.
+- Try using the local checkout path instead: `"./.opencode/plugins/ponytail.mjs"`.
+
+## Rules not applying
+
+**Problem**
+
+The ponytail ruleset does not appear in the agent's behavior.
+
+**Cause**
+
+The plugin is not active, or the mode is set to `off`.
+
+**Solution**
+
+- Run `/ponytail` to check the current mode.
+- If `off`, run `/ponytail full` to enable.
+- Verify the plugin is listed in `opencode.json` and restart OpenCode.
+- Check the plugin was installed correctly with `opencode plugin list`.
+
+## Node.js not found
+
+**Problem**
+
+Lifecycle hooks fail with a Node.js error.
+
+**Cause**
+
+The hooks need `node` on the PATH, but it is not available in the non-interactive shell.
+
+**Solution**
+
+- Verify `node --version` works in a new terminal.
+- Nix/nvm users: ensure Node.js is on the PATH for non-interactive shells (e.g., via `~/.zshenv` or a nix-darwin activation script).
+- The skills still work without Node.js; only the always-on activation is affected.
+
+## Mode not persisting
+
+**Problem**
+
+The mode resets to default after restarting OpenCode.
+
+**Cause**
+
+The state file cannot be written or read.
+
+**Solution**
+
+- Check that `~/.config/opencode/` is writable.
+- Verify `~/.config/opencode/.ponytail-active` exists and is readable: `cat ~/.config/opencode/.ponytail-active`.
+- Set `PONYTAIL_DEFAULT_MODE` to your preferred mode as a fallback.
+
+## Commands not available
+
+**Problem**
+
+`/ponytail` or `/ponytail-review` slash commands do not appear.
+
+**Cause**
+
+The plugin commands are not registered, or the host does not support slash commands.
+
+**Solution**
+
+- Verify the plugin loaded successfully.
+- Some adapters (Cursor, Windsurf, Cline) load only the ruleset, not the commands.
+- Codex uses `@ponytail-review` instead of `/ponytail-review`.
+- For OpenCode, ensure the plugin config points to the correct path or npm package.
+
+## Plugin conflicts
+
+**Problem**
+
+Ponytail conflicts with other plugins or skills.
+
+**Cause**
+
+Multiple plugins modify the system prompt in conflicting ways.
+
+**Solution**
+
+- Run `/ponytail off` to disable ponytail and isolate the issue.
+- Review other installed plugins for system prompt modifications.
+- Adjust mode to `lite` for a gentler nudge that may conflict less.
+
+## Excessive minimalism
+
+**Problem**
+
+The agent is cutting too much code, including necessary functionality.
+
+**Cause**
+
+`ultra` mode may be too aggressive for the task.
+
+**Solution**
+
+- Switch to `full` or `lite` mode.
+- Be explicit in your prompts about what you expect.
+- Ponytail never cuts validation, error handling, security, or accessibility by design.

package/framework/references/standards/api.md

@@ -0,0 +1,44 @@
+# API Standard
+
+## Purpose
+
+Define reusable backend engineering rules for API decisions across projects. This standard is canonical guidance for related skills.
+
+## Rules
+
+- Use HTTP methods by semantic meaning: GET for reads, POST for creates, PUT for full replacement, PATCH for partial update, DELETE for removal.
+- Version the API via URL prefix (`/v1/`) or accept header; never break a published version without a deprecation cycle.
+- Return standard HTTP status codes: 200 for success, 201 for created, 204 for deleted, 400 for bad request, 401 for unauthenticated, 403 for forbidden, 404 for not found, 409 for conflict, 422 for validation, 429 for rate limited, 5xx for server errors.
+- All errors use a consistent JSON envelope: `{"error": {"code": "...", "message": "...", "details": {...}}}`.
+- Paginate list endpoints using cursor-based pagination; return `next_cursor` and `has_more` in the response body.
+- Use request IDs on mutating endpoints and return them in responses for idempotency guarantees.
+
+## Best Practices
+
+- Design resources around business nouns, not actions; use sub-resources for relationships (`/orders/{id}/items`).
+- Make response bodies backward-compatible: never remove fields, never change field types; add fields as optional.
+- Rate limit by client (API key or IP); return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers and 429 with `Retry-After`.
+- Validate all input at the boundary using a schema (JSON Schema, protobuf, or equivalent); reject unknown fields.
+- Use idempotency keys (`Idempotency-Key` header) for POST endpoints that create resources.
+
+## Anti-patterns
+
+- Using GET for mutating operations or POST for pure reads.
+- Returning 200 with an error body instead of the appropriate 4xx status code.
+- Changing a field's meaning or type within the same API version.
+- Exposing internal IDs or database identifiers when opaque public IDs are feasible.
+- Nesting resources deeper than two levels; flatten or use query parameters.
+
+## Checklist
+
+- [ ] HTTP method matches the operation's semantics.
+- [ ] Error responses follow the standard envelope with actionable messages.
+- [ ] Pagination uses cursor-based tokens, not page numbers.
+- [ ] Rate limiting headers are present on all endpoints.
+- [ ] New fields are optional or have sensible defaults; no breaking changes.
+
+## Related Skills
+
+- `skills/backend-engineer/SKILL.md`
+- `skills/code-review/SKILL.md`
+- `skills/backend-best-practices/references/api-design.md`

package/framework/references/standards/architecture.md

@@ -0,0 +1,43 @@
+# Architecture Standard
+
+## Purpose
+
+Define reusable backend engineering rules for architecture decisions across projects. This standard is canonical guidance for related skills.
+
+## Rules
+
+- Enforce strict layering: presentation depends on application depends on domain; infrastructure depends on abstractions, not concrete types.
+- Dependencies must point inward: inner layers (domain) define interfaces; outer layers (infrastructure) implement them.
+- A module must have a single reason to change; group code by business domain, not by technical role.
+- Public API surfaces must be small and explicit; hide internal details behind package/module boundaries.
+- No circular dependencies between modules, packages, or layers; enforce with build-time checks.
+
+## Best Practices
+
+- Use the Ports & Adapters pattern: business logic depends on interfaces (ports), external systems plug in via adapters.
+- Communicate between bounded contexts through asynchronous messages or a published anti-corruption layer; never share internal types.
+- Keep domain logic free of framework annotations, serialization concerns, and database primitives.
+- Draw architectural decisions as C4 diagrams (Context, Container, Component, Code) and review them before building.
+- Each module should be testable in isolation by swapping real adapters with test doubles at the port boundary.
+
+## Anti-patterns
+
+- Anemic domain model where business logic leaks into services and the domain layer is just getters and setters.
+- Using dependency injection to wire everything together while still calling concrete classes directly.
+- Big Ball of Mud: no clear boundaries, arbitrary cross-module references, mixed concerns in a single package.
+- Leaking infrastructure concepts (HTTP request objects, database connections, serialization formats) into domain logic.
+- Premature microservices: extracting services before understanding the bounded context, adding network overhead without cohesion benefit.
+
+## Checklist
+
+- [ ] Dependency direction is verified: domain depends on nothing, infrastructure depends on domain.
+- [ ] Each module has a well-defined public API and internal package is hidden.
+- [ ] No circular dependencies exist (verified by tooling).
+- [ ] Domain code is framework-independent and testable without infrastructure.
+- [ ] Architecture decision record (ADR) exists for any significant structural choice.
+
+## Related Skills
+
+- `skills/backend-engineer/SKILL.md`
+- `skills/code-review/SKILL.md`
+- `skills/backend-best-practices/references/architecture-review.md`

package/framework/references/standards/database.md

@@ -0,0 +1,43 @@
+# Database Standard
+
+## Purpose
+
+Define reusable backend engineering rules for database decisions across projects. This standard is canonical guidance for related skills.
+
+## Rules
+
+- Every table must have a single-column, auto-incrementing or UUID primary key named `id`.
+- All columns must be `NOT NULL` unless there is an explicit business reason for nullability; model optionality through separate tables where appropriate.
+- Define foreign key constraints for all relationships; use `ON DELETE RESTRICT` by default, `ON DELETE CASCADE` only after documented reasoning.
+- Index every column that appears in a `WHERE`, `JOIN`, `ORDER BY`, or `GROUP BY` clause; use composite indexes when filtering on multiple columns.
+- All migrations must be reversible (provide `down` migration); never alter or drop a column without a zero-downtime rollout plan.
+
+## Best Practices
+
+- Name tables as plural nouns (`orders`, `users`) and columns as snake_case descriptive names (`created_at`, `order_status`).
+- Use database-level CHECK constraints for business invariants (e.g., `amount > 0`, `status IN ('pending', 'paid')`).
+- Keep transactions short; never hold a transaction open across network calls or user interaction.
+- Use `EXPLAIN ANALYZE` on every new or modified query before deploying; aim for sequential scans on tables under 10k rows, index scans on larger tables.
+- Pool connections with a max of `(2 × CPU cores) + 1` per service instance; configure statement timeouts at the connection level.
+
+## Anti-patterns
+
+- Using a database as a message queue (polling tables for work); use a dedicated message broker instead.
+- Storing JSON blobs that are queried or joined on; promote queryable fields to proper columns with indexes.
+- Running application logic in triggers or stored procedures; keep business logic in application code.
+- SELECT * in production code; always list explicit columns.
+- Schema changes (migrations) applied at application startup; use a separate migration tool with gated rollout.
+
+## Checklist
+
+- [ ] Every table has an `id` primary key, proper indexes, and foreign keys with explicit `ON DELETE` behavior.
+- [ ] All queries are reviewed with `EXPLAIN ANALYZE`; no sequential scans on hot paths.
+- [ ] Connection pool limits and statement timeouts are configured.
+- [ ] Migrations are reversible and have been tested against production-sized data.
+- [ ] No sensitive data (passwords, tokens, PII) is stored without encryption or hashing consideration.
+
+## Related Skills
+
+- `skills/backend-engineer/SKILL.md`
+- `skills/code-review/SKILL.md`
+- `skills/backend-best-practices/references/database-design.md`

package/framework/references/standards/debugging.md

@@ -0,0 +1,44 @@
+# Debugging Standard
+
+## Purpose
+
+Define reusable backend engineering rules for debugging decisions across projects. This standard is canonical guidance for related skills.
+
+## Rules
+
+- Reproduce the issue in a non-production environment before changing any code.
+- Isolate one variable at a time (binary search through commits, configs, inputs, or environment differences).
+- Correlate logs, metrics, and traces by a shared identifier (trace_id, request_id, correlation_id) before forming a hypothesis.
+- Fix root causes, not symptoms. A fix that does not prevent recurrence is incomplete.
+- Preserve all diagnostic evidence (logs, dumps, metrics snapshots) before restarting or rolling back.
+
+## Best Practices
+
+- Start with the most recent change when diagnosing a regression; git bisect is faster than manual inspection.
+- Write a hypothesis before each experiment: "If X is the cause, then Y will happen when I do Z."
+- Add a regression test or monitoring check after the fix to detect recurrence automatically.
+- Pair debug with a colleague when stuck for more than 30 minutes; fresh eyes see different assumptions.
+- Document the root cause and fix in a shared incident log or postmortem.
+
+## Anti-patterns
+
+- Changing code based on assumptions without reproducing the issue first.
+- Stopping at the first plausible cause without ruling out alternative explanations.
+- Cherry-picking evidence that supports the current hypothesis while ignoring contradictory data.
+- Applying hotfixes in production without understanding the root cause.
+- Restarting services to "fix" a problem, which destroys diagnostic evidence.
+
+## Checklist
+
+- [ ] The issue is reproduced in a safe environment.
+- [ ] Logs, metrics, and traces are correlated and examined together.
+- [ ] A root cause hypothesis explains all observed symptoms.
+- [ ] Alternative hypotheses have been ruled out.
+- [ ] The fix addresses the root cause, not just the symptom.
+- [ ] A regression test or monitor can detect recurrence.
+
+## Related Skills
+
+- `skills/backend-engineer/SKILL.md`
+- `skills/code-review/SKILL.md`
+- `skills/backend-best-practices/references/debugging.md`

package/framework/references/standards/documentation.md

@@ -0,0 +1,43 @@
+# Documentation Standard
+
+## Purpose
+
+Define reusable backend engineering rules for documentation decisions across projects. This standard is canonical guidance for related skills.
+
+## Rules
+
+- Every architectural decision that is non-obvious, costly to reverse, or has tradeoffs must have an ADR in `docs/adr/` following the MADR template.
+- API endpoints must have a machine-readable specification (OpenAPI 3.x) that is the single source of truth; keep it in the same repository as the implementation.
+- Every service must have a runbook in `docs/runbooks/` covering startup, health checks, common failure modes, and recovery steps.
+- Documentation lives as close to code as possible: inline comments explain "why not what", module-level docs explain purpose, and README explains how to run/test/deploy.
+- Review documentation in the same PR as the code change; docs that ship separately are never written.
+
+## Best Practices
+
+- Write design docs before building non-trivial features; include context, proposed solution, alternatives considered, and open questions.
+- Keep README files structured: title, description, quick start, configuration, deployment, and links to detailed docs.
+- Use diagrams in ADRs and design docs (Mermaid or PlantUML) to communicate system relationships visually.
+- Document failure modes and their mitigation in runbooks, including step-by-step commands and expected output.
+- Set a 30-day freshness SLA for runbooks; stale runbooks must be surfaced by a scheduled review.
+
+## Anti-patterns
+
+- README files that are outdated, have no structure, or list dead commands and obsolete environment variables.
+- Writing design docs after implementation; the doc should guide the build, not describe what was built.
+- Documenting obvious code behavior ("this function adds two numbers") instead of the rationale and constraints.
+- Scattering documentation across wikis, Notion, Google Docs, and the repo with no single source of truth.
+- ADRs that describe only the chosen solution without documenting the alternatives considered and rejected.
+
+## Checklist
+
+- [ ] Code changes include or update relevant documentation in the same PR.
+- [ ] ADRs exist for every significant architectural decision.
+- [ ] API spec (OpenAPI) is in the repo and matches the implementation.
+- [ ] Runbook is up to date and tested against a staging environment.
+- [ ] README reflects the current state of the project.
+
+## Related Skills
+
+- `skills/backend-engineer/SKILL.md`
+- `skills/code-review/SKILL.md`
+- `skills/documentation/SKILL.md`