### POST /api/v1/users

Create a new user account.

**Authentication:** Bearer token (required)

**Request body:**

| Field    | Type   | Required | Description              |
|----------|--------|----------|--------------------------|
| email    | string | yes      | Valid email address       |
| name     | string | yes      | Display name (2-100 chars)|
| role     | string | no       | One of: admin, member     |

**Response (201 Created):**

```json
{
  "id": "usr_abc123",
  "email": "dev@example.com",
  "name": "Ada Lovelace",
  "role": "member",
  "created_at": "2025-01-15T10:30:00Z"
}

> Always include a realistic response example with plausible data, not placeholder
> values like "string" or "0".

### Write a step-by-step tutorial

Use this structure for every tutorial:

1. **Title** - "How to [accomplish specific goal]"
2. **Prerequisites** - What the reader needs before starting (tools, accounts, prior knowledge)
3. **Steps** - Numbered, each with one action and its expected outcome
4. **Verify** - How to confirm the tutorial worked
5. **Next steps** - Where to go from here

Each step should follow this pattern:

```markdown
## Step 3: Configure the database connection

Add your database URL to the environment file:

```bash
echo 'DATABASE_URL=postgres://localhost:5432/myapp' >> .env

> Never assume the reader can infer a step. If you deleted a step and the tutorial
> would still work, the step is load-bearing for understanding, not execution - keep
> it but mark it as context.

### Write an Architecture Decision Record (ADR)

Use the Michael Nygard format:

```markdown
# ADR-007: Use PostgreSQL for the primary datastore

## Status

Accepted (2025-03-10)

## Context

The application needs a relational datastore that supports ACID transactions,
JSON columns for semi-structured data, and full-text search. The team has
production experience with PostgreSQL and MySQL.

## Decision

Use PostgreSQL 16 as the primary datastore.

## Consequences

- **Positive:** Native JSONB support eliminates the need for a separate
  document store. Full-text search via tsvector avoids an Elasticsearch
  dependency.
- **Negative:** Requires operational expertise for vacuum tuning and
  connection pooling at scale. Team must learn PostgreSQL-specific features
  (CTEs, window functions) that differ from MySQL.
- **Neutral:** Migration tooling (pgloader) is available if we need to move
  data from the existing MySQL instance.

# Runbook: Database failover to read replica

**Severity:** SEV-1 (data serving impacted)
**Owner:** Platform team
**Last tested:** 2025-02-20
**Estimated time:** 10-15 minutes

## Symptoms

- Application returns 500 errors on all database-backed endpoints
- Database primary shows `connection refused` or replication lag > 60s

## Prerequisites

- Access to AWS console (production account)
- `kubectl` configured for the production cluster
- Pager notification sent to #incidents channel

## Steps

1. Verify the primary is actually down:
   ```bash
   pg_isready -h primary.db.internal -p 5432

> Every runbook step must include the exact command to run and the expected output.
> Never write "check the database" without specifying the exact check.

### Write architecture documentation

Use the C4 model approach - zoom in through layers:

1. **System context** - What is this system and how does it fit in the landscape?
2. **Container diagram** - What are the deployable units (services, databases, queues)?
3. **Component diagram** - What are the major modules inside a container?
4. **Code diagram** - Only for genuinely complex logic (optional)

For each layer, include a diagram (Mermaid, PlantUML, or ASCII) plus 2-3 paragraphs
of explanatory prose. See `references/architecture-docs.md` for templates.

### Review existing documentation

Apply this checklist when reviewing any doc:

- [ ] **Accuracy** - Does the doc match the current state of the system?
- [ ] **Completeness** - Are there gaps where a reader would get stuck?
- [ ] **Audience** - Is the language appropriate for the target reader?
- [ ] **Structure** - Can the reader find what they need in under 30 seconds?
- [ ] **Examples** - Does every abstract concept have a concrete example?
- [ ] **Freshness** - Is there a "last updated" date? Is it recent?
- [ ] **Actionability** - Can the reader do something after reading this?

---

## Anti-patterns / common mistakes

| Mistake | Why it's wrong | What to do instead |
|---|---|---|
| Wall of text | Engineers stop reading after the first paragraph without visual breaks | Use headings every 3-5 paragraphs, bullet lists for items, tables for structured data |
| Documenting internals as tutorials | Implementation details change frequently and confuse new users | Separate reference docs (internals) from tutorials (user journey) |
| Missing prerequisites | Reader gets stuck at step 3 because they don't have a required tool | List every prerequisite at the top, including versions |
| "Obvious" steps omitted | What's obvious to the author is not obvious to the reader | Write as if the reader has never seen the codebase before |
| Stale screenshots | Screenshots go stale faster than any other doc element | Prefer text-based examples (code blocks, CLI output) over screenshots |
| ADRs written after the fact | Retroactive ADRs lose the context and rejected alternatives | Write the ADR as part of the decision process, not after implementation |
| Runbooks without rollback | On-call engineer makes things worse because there is no undo path | Every runbook must include a rollback section |

---

## Gotchas

1. **Tutorials that work on the author's machine often fail for readers** - Missing environment prerequisites, OS-specific path differences, and version mismatches are the most common failure points. Test every tutorial on a clean environment with no prior setup before publishing.

2. **ADRs edited after acceptance lose their value** - The entire point of an ADR is preserving the reasoning at the time of the decision, including rejected alternatives. Editing an accepted ADR to "clean it up" erases the historical context. If the decision changed, write a new ADR that supersedes the original.

3. **OpenAPI specs and actual API behavior diverge silently** - Without automated contract testing, your API docs will drift from the implementation. Integrate OpenAPI validation in CI to catch discrepancies before they reach developers consuming the API.

4. **Runbooks tested only at creation become unreliable** - A runbook that has never been executed in a real or simulated incident will fail when needed. Schedule quarterly runbook dry runs and update the "Last tested" date. A runbook with no test date should be treated as untrusted.

5. **Audience mismatch between docs is harder to fix than missing docs** - A tutorial written for experienced engineers will block new hires; architecture docs written for junior engineers will be ignored by seniors. Define the audience explicitly at the top of every document and review it when onboarding new readers.

---

## References

For detailed templates and examples on specific document types, read the relevant
file from `references/`:

- `references/api-docs.md` - OpenAPI patterns, REST vs GraphQL doc strategies, response examples
- `references/tutorials.md` - Tutorial structure, progressive disclosure, common pitfalls
- `references/architecture-docs.md` - C4 model templates, diagram tools, living doc strategies
- `references/adrs.md` - ADR templates (Nygard, MADR), lifecycle management, indexing
- `references/runbooks.md` - Runbook structure, severity levels, testing cadence, automation

Only load a references file if the current task requires deep detail on that topic.

---

## Companion check

> On first activation of this skill in a conversation: check which companion skills are installed by running `ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null`. Compare the results against the `recommended_skills` field in this file's frontmatter. For any that are missing, mention them once and offer to install:
> ```
> npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>
> ```
> Skip entirely if `recommended_skills` is empty or all companions are already installed.