// Load for technical documentation tasks — README authoring, ADRs, runbooks, API docs, inline comments, and Mermaid diagrams. Auto-load when asked to write, review, or improve documentation for code, pipelines, or architecture.
| name | technical-writing |
| description | Load for technical documentation tasks — README authoring, ADRs, runbooks, API docs, inline comments, and Mermaid diagrams. Auto-load when asked to write, review, or improve documentation for code, pipelines, or architecture. |
These are wastes of tokens that degrade trust in the documentation:
# increment counter above counter += 1# <Project Name>
One sentence: what this does and for whom.
## Prerequisites
- Python 3.12+, uv
- GCP project with [list specific APIs enabled]
- [Any other hard requirements]
## Setup
```bash
uv sync
cp .env.example .env
# Edit .env — see .env.example for required vars
gcloud auth application-default login
# Most common operation
uv run python -m src.main --date 2026-01-15
# Run tests
uv run pytest
[One Mermaid diagram or a 3-5 line description of the data flow. Not a full design doc — that's DESIGN.md.]
[Link to runbook if exists. Key failure modes and their fixes. Nothing else.]
**Rules:**
- No badges unless the CI is actually configured and passing.
- No "Contributing" section for solo projects.
- No "License" section unless this is public OSS.
- Setup section must be copy-pasteable. Test it.
---
## ADR template
One ADR per significant decision. Stored in `docs/adr/NNNN-short-title.md`.
```markdown
# ADR-NNNN: <Title>
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
## Context
The problem or constraint that forced this decision. What was the situation?
What options existed? Keep to 3-5 sentences.
## Decision
What we chose and why. One clear statement, then the reasoning.
Reference alternatives considered and why they were rejected.
## Consequences
**Positive:**
- [Concrete benefit]
**Negative / trade-offs:**
- [Concrete cost or limitation]
**Risks:**
- [What could go wrong and how we'd detect it]
Rules:
For any pipeline or service running in production.
# Runbook: <Pipeline or Service Name>
**Owner:** <team or person>
**Last tested:** YYYY-MM-DD
## What this does
One paragraph. Input → transformation → output.
## Normal operation
What does healthy look like? Expected run duration, row counts, log patterns.
## Failure modes
### <Failure mode 1>
**Symptom:** What you see (log message, alert, metric).
**Cause:** Why it happens.
**Fix:**
```bash
# Exact commands to run
Escalate if: The fix doesn't work within X minutes.
...
gcloud run jobs execute JOB_NAME \
--region=europe-west1 \
--args="--date=2026-01-15"
bq query --use_legacy_sql=false \
"SELECT * FROM \`project.dataset.pipeline_log\` ORDER BY run_at DESC LIMIT 10"
---
## Mermaid diagrams
Use for data flows, pipeline architecture, and decision trees. Not for entity-relationship — use a schema file instead.
```mermaid
flowchart LR
A[GCS Raw] -->|Cloud Run Job| B[BQ Staging]
B -->|dbt build| C[BQ Marts]
C -->|Looker Studio| D[Dashboard]
E[Pub/Sub] -->|BQ Subscription| A
Rules:
flowchart LR for pipelines (left to right).flowchart TD for hierarchies (top down).Comment when:
# noqa or type: ignore is used — always explain whyDo not comment when:
# BQ charges for bytes scanned at the partition level even with a LIMIT clause.
# This filter on _PARTITIONDATE must come before any JOIN to avoid a full scan.
WHERE _PARTITIONDATE = DATE(run_date)
