hive-skills 0.1.0

package/assets/skills/authored/python-api/composable/mini/06-pagination-filtering.md

@@ -0,0 +1,44 @@
+---
+pairs-with:
+  - code-review/02-security-review.md
+---
+
+# Pagination, Filtering & Sorting
+
+Never return an unbounded collection. Offer limit/offset for simple cases, keyset (cursor) for large or fast-changing data.
+
+**Limit/offset:**
+```python
+class Page(BaseModel):
+    limit: int = Field(20, ge=1, le=100)
+    offset: int = Field(0, ge=0)
+
+@router.get("", response_model=PageOut[UserOut])
+def list_users(p: Page = Depends(), db: Session = Depends(get_db)):
+    q = select(User).order_by(User.id)
+    total = db.scalar(select(func.count()).select_from(User))
+    rows = db.scalars(q.limit(p.limit).offset(p.offset)).all()
+    return {"items": rows, "total": total, "limit": p.limit, "offset": p.offset}
+```
+
+Note the `le=100` cap: clients can't request unbounded pages.
+
+**Keyset pagination** avoids the deep-offset performance cliff (offset scans and discards skipped rows): `WHERE id > :cursor ORDER BY id LIMIT :n`, returning the last id as the next cursor. Use it for large tables and infinite scroll.
+
+**Deterministic ordering is mandatory.** Always apply an `ORDER BY` with a unique tiebreaker (e.g. `ORDER BY created_at, id`). Without it, rows can shift between pages and clients see duplicates or gaps.
+
+**Safe filtering & sorting** (the security-critical part):
+- Expose an explicit allowlist of filter fields as typed query params. Never build SQL from raw client strings and never `eval` a filter expression.
+- Map sort keys through a whitelist dict to columns:
+
+```python
+SORTABLE = {"email": User.email, "created": User.created_at}
+col = SORTABLE.get(sort_key)
+if col is None:
+    raise HTTPException(400, "invalid sort field")
+q = q.order_by(col.desc() if descending else col.asc())
+```
+
+This prevents SQL injection and stops clients sorting by or filtering on private columns. Always use parameterized queries / the ORM, never string interpolation.
+
+**Response metadata.** Return enough for the client to navigate: the items plus `limit`/`offset` (or a `next_cursor`), and a `total` only when it's cheap: a `COUNT(*)` over a huge filtered table can cost as much as the page query itself, so for large datasets prefer cursor pagination with a `has_more` flag and omit the total. Cap the maximum page size server-side (`le=100`) regardless of what the client asks for, so no single request can pull the whole table.

package/assets/skills/authored/python-api/composable/mini/07-async-performance.md

@@ -0,0 +1,30 @@
+---
+pairs-with:
+  - code-review/06-performance.md
+  - code-review/04-concurrency.md
+---
+
+# Async, Performance & the Event Loop
+
+FastAPI runs `async def` handlers on the event loop and plain `def` handlers in a threadpool. Understanding this split is essential for performance.
+
+**The cardinal sin:** calling blocking I/O inside an `async def` handler (a sync DB driver, `requests`, `time.sleep`, or any CPU-heavy loop). It stalls the entire event loop, so every concurrent request stalls with it. Fixes:
+- Make the handler plain `def` (FastAPI runs it in a threadpool), **or**
+- Use async libraries: `httpx.AsyncClient` instead of `requests`, async SQLAlchemy / async drivers, `asyncio.sleep` instead of `time.sleep`.
+
+Don't mix them: a `def` handler calling async code, or an `async def` handler calling blocking code, are both wrong.
+
+**Database performance:**
+- Use connection pooling (configure pool size to match worker count).
+- Prevent N+1 queries with eager loading (`selectinload`, `joinedload`) when you access relationships in a loop.
+- Push filtering/aggregation into SQL rather than loading rows and processing in Python.
+
+**Outbound calls:**
+- Reuse a single HTTP client with connection pooling; don't create a client per request.
+- **Set timeouts on every outbound call**: a hung dependency without a timeout ties up a worker indefinitely.
+
+**Caching:** add caching for hot read paths, using HTTP `ETag`/`Cache-Control` headers for client/proxy caching, or Redis for shared server-side caching. Cache computed or expensive-to-fetch data with a sensible TTL and clear invalidation rules.
+
+**General:** avoid mutable default arguments and shared global mutable state across requests (each request should get its own state). Profile before optimizing; most latency is I/O (DB and downstream calls), not Python CPU.
+
+**Production concurrency model:** run multiple worker processes (`uvicorn`/`gunicorn`, sized roughly to cores for CPU-bound apps, higher for I/O-bound) behind a process manager. Each worker has its own event loop; scaling out processes is how you use multiple cores, since one Python process is GIL-bound for CPU work. Offload genuinely heavy or long-running work (report generation, image processing, third-party fan-out) to a background task queue (Celery, RQ, `arq`) and return `202 Accepted` with a status URL, rather than blocking a request worker for seconds.

package/assets/skills/authored/python-api/composable/mini/08-testing.md

@@ -0,0 +1,45 @@
+---
+pairs-with:
+  - code-review/08-missing-tests.md
+---
+
+# Testing with pytest + TestClient
+
+Test through the API with `TestClient` (sync) or `httpx.AsyncClient` (async). Override dependencies to inject a test DB and fake auth: this is the payoff of dependency injection.
+
+```python
+from fastapi.testclient import TestClient
+
+@pytest.fixture
+def client():
+    app.dependency_overrides[get_db] = lambda: test_session
+    with TestClient(app) as c:
+        yield c
+    app.dependency_overrides.clear()
+
+def test_create_user(client):
+    r = client.post("/api/v1/users", json={"email": "a@b.com",
+                    "password": "s3cret!!", "full_name": "A"})
+    assert r.status_code == 201
+    assert "password" not in r.json()   # sensitive field must not leak
+
+def test_rejects_short_password(client):
+    r = client.post("/api/v1/users", json={"email": "a@b.com",
+                    "password": "x", "full_name": "A"})
+    assert r.status_code == 422
+```
+
+**Test the contract, not the implementation:**
+- Status codes for success and each error path.
+- Response shape, and that sensitive fields (password hashes, internal ids) are absent.
+- Auth enforced: unauthenticated returns `401`, wrong-user/role returns `403`.
+- Validation rejects bad input (`422`); pagination bounds hold (`limit` cap respected).
+
+**Isolation & data:**
+- Use a fresh transactional DB per test: create schema then wrap each test in a rollback, or use a disposable SQLite / testcontainers Postgres.
+- `pytest.fixture` for setup/teardown; `parametrize` for edge cases.
+- Build test data with factories (`factory_boy` or plain builder functions), not copy-pasted dicts.
+
+Keep tests fast and isolated. Mock only external services (payment gateways, third-party APIs); never mock your own code, or you test the mock instead of the behavior. A test that passes against a mock of your service proves nothing about the service.
+
+Cover the full contract deliberately: a happy-path test per endpoint, plus one test per error branch (404, 409, 422), an auth test (401 unauthenticated, 403 wrong role/owner), and a pagination test asserting the `limit` cap is enforced. Prefer many small focused tests over a few sprawling ones: when a focused test fails, its name tells you what broke.

package/assets/skills/authored/python-api/composable/mini/09-middleware-observability.md

@@ -0,0 +1,29 @@
+---
+pairs-with:
+  - code-review/02-security-review.md
+---
+
+# Middleware, CORS, Observability & Rate Limiting
+
+Cross-cutting concerns belong in middleware and app-level config, not scattered through individual handlers.
+
+**CORS.** If a browser front-end on another origin calls the API, configure `CORSMiddleware` with an explicit allowlist of origins. Never combine `allow_origins=["*"]` with `allow_credentials=True`: it is both insecure and rejected by browsers. List the exact front-end origins, methods, and headers you actually need.
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+**Request logging & correlation.** Add middleware that assigns each request a correlation id (from an incoming `X-Request-ID` header or a freshly generated UUID), binds it to the logger, and logs method, path, status code, and duration. Structured JSON logs make a request traceable across services. Never log request bodies that may carry secrets or PII.
+
+**Rate limiting.** Protect auth and expensive endpoints with rate limits (a library like `slowapi`, or an upstream API gateway). Limit by client identity or IP, return `429` with a `Retry-After` header when a caller exceeds the limit, and apply stricter limits to login/token endpoints to blunt credential-stuffing attacks.
+
+**Health & readiness.** Expose a lightweight `/health` (the process is up) and a `/ready` (dependencies are reachable) endpoint for orchestrators and load balancers. Keep `/health` dependency-free so a slow database doesn't make the instance look dead and get killed. Emit basic metrics (request count, latency, error rate) for monitoring dashboards and alerts.
+
+**Timeouts everywhere.** Set request and outbound-call timeouts so a slow client or hung downstream can't hold a worker indefinitely. Combined with rate limiting, this is your first line of defense against both accidental overload and abuse.

package/assets/skills/authored/tech-writing/composable/BUNDLE.md

@@ -0,0 +1,220 @@
+<!-- GENERATED by tools/hive.py compile. Do not hand-edit. -->
+# tech-writing: Compiled Skill Bundle (v1.0.0)
+
+All composable mini-skills for `tech-writing` concatenated in index order, frontmatter stripped. Regenerate with `tools/hive.py compile <skill-dir>`. Do not edit by hand.
+
+---
+<!-- module: 01-audience-analysis.md -->
+
+# Audience Analysis & Job-to-be-Done
+
+Never write a doc until you can name three things: (a) the reader, (b) the task they are mid-way through, and (c) what "done" looks like for them. Documentation is read by people under load (mid-incident, mid-integration, mid-evaluation), not studied at leisure.
+
+Segment readers on three axes:
+
+- **Expertise**: novice vs. expert. Novices need concepts and orientation; experts need a searchable reference and copy-paste snippets. Do not force an expert through a tutorial to find one flag name.
+- **Goal**: evaluating (should I adopt this?), integrating (make it work now), operating (keep it running), debugging (why did it break?). Each goal wants a different document type and depth.
+- **Context of use**: at a terminal, on a phone mid-incident, in a procurement meeting. Context dictates length, scannability, and where the answer must appear.
+
+**Worked example.** "How do I authenticate?" comes from at least two readers. The evaluator wants to know *which* auth methods exist and their tradeoffs: one paragraph and a table. The integrator wants a working request *right now*: a labeled code block with a real-looking token. Answer both, in that order, and label each so readers skip to their part.
+
+**State assumed prior knowledge explicitly at the top**: "This guide assumes a running cluster and kubectl configured." Unstated assumptions are the single largest cause of doc failure: the reader hits an undocumented prerequisite, gets stuck, and blames the product.
+
+Practical habits:
+- Write a one-line reader statement before drafting: "For an integrator who already has an API key and wants their first successful call."
+- List prerequisites as an up-front checklist, not scattered inline.
+- When a page must serve two audiences, split it into clearly labeled sections rather than blending. Blended docs frustrate both readers at once.
+- Prefer specifics the reader can check ("you need Node 18+") over vague reassurance ("recent Node").
+
+The audience decision drives every later choice: document type, structure, tone, and how much you explain versus assume. Get it wrong and even flawless prose fails, because it answers a question the reader did not ask.
+
+---
+<!-- module: 02-document-types.md -->
+
+# Choosing the Right Document Type
+
+Reader goals map to four distinct, non-interchangeable document types. Mixing them in one page is the most common structural mistake in documentation.
+
+- **Tutorial** (learning-oriented): a guided, guaranteed-to-succeed lesson for a newcomer. Linear, opinionated, one happy path, no alternatives, no error branches. Success = the reader built something and feels competent.
+- **How-to / task guide** (problem-oriented): steps to accomplish a specific real-world task the reader already knows they need. Assumes competence. May list variations. Success = task completed.
+- **Reference** (information-oriented): exhaustive, accurate description of the machinery: every parameter, return value, error code, config key. Dry, consistent, austere. Success = the reader found the exact fact and trusts it.
+- **Explanation / concept** (understanding-oriented): the *why*: architecture, tradeoffs, mental models. Read away from the keyboard. Success = the reader can reason about edge cases.
+
+Keep these separate. A reference page cluttered with tutorial hand-holding frustrates experts; a tutorial padded with reference tables loses novices. When a page feels muddled, it is usually two types fighting. Split it.
+
+**How to tell them apart in practice.** Ask what the reader is doing:
+- Learning the tool for the first time → tutorial.
+- Has a specific job to finish → how-to.
+- Needs a precise fact mid-work → reference.
+- Wants to understand tradeoffs before deciding → explanation.
+
+**Worked example.** "Authentication" often needs three pages, not one: a *tutorial* that walks a newcomer through their first authenticated call; a *reference* listing every auth method, scope, token lifetime, and error code; and an *explanation* of the auth model and its threat assumptions. One page trying to be all three serves none well.
+
+Signs you have mixed types: a tutorial with a giant parameter table; a reference page with encouraging asides ("Great, now let's..."); a how-to that pauses to explain architecture. Move the mismatched content to the page whose type it fits, and link between them.
+
+Parallel structure within a type helps: every API method reference page should share one shape (Description → Parameters → Returns → Errors → Example) so readers navigate by muscle memory.
+
+---
+<!-- module: 03-readme-quickstart-changelog.md -->
+
+# README, Quickstart, Changelog & Release Notes
+
+**README**: a landing page and router, not a manual. Order: one-sentence description of what this is and who it is for; a short "why/what" paragraph; minimal install; a **60-second quickstart** that produces a visible result; then links out to deeper docs. Put the single most impressive working example above the fold. Badges and tables of contents come *after* value is demonstrated, not before. A reader should learn what the thing is and see it work within the first screen.
+
+**Quickstart**: the shortest path from zero to a first success, ideally under 5 minutes. List prerequisites up front as a checklist. Every step is copy-pasteable and idempotent where possible. End with a concrete checkpoint ("you should now see X") and exactly one clear next step. Cut every optional detail and link it instead; a quickstart that branches has failed at being quick.
+
+**Changelog vs release notes**: two artifacts for two audiences; do not conflate them.
+- A **changelog** is terse, chronological, developer-facing. Group entries per version as Added / Changed / Deprecated / Removed / Fixed / Security (the Keep a Changelog convention). Each entry is one line stating what changed.
+- **Release notes** are narrative and user-facing. Lead with the headline value ("Exports are now 10x faster"), explain impact, and call out breaking changes prominently.
+
+Both must be **newest first, dated, with a stable version identifier**. Never make a reader diff two versions to discover what changed. That is the changelog's entire job.
+
+**Worked example (a changelog entry vs a release note for the same change):**
+- Changelog: `### Changed` / `- \`export()\` now streams results instead of buffering (#412).`
+- Release note: "Large exports no longer run out of memory. `export()` now streams, so multi-gigabyte reports complete reliably. No code change needed unless you relied on the full result being in memory at once (see [migration])."
+
+Common failures: a README that explains philosophy before showing the tool work; a quickstart padded with configuration options; release notes that bury a breaking change in a bullet list. Fix each by ruthlessly front-loading the reader's payoff and pushing detail to linked reference pages.
+
+---
+<!-- module: 04-information-architecture.md -->
+
+# Information Architecture
+
+How to structure pages and doc sets so readers find and consume the right thing fast.
+
+- **One page, one job.** If a page answers more than one reader question, split it. Competing half-answers on multiple pages are worse than one canonical page. Ensure exactly one authoritative page per topic.
+- **Front-load the answer.** Use the inverted pyramid: conclusion or result first, then detail, then background. Readers scan the first line of each section and bail early, so the payoff must come first. "To reset your password, open Settings" beats "Open Settings, which you can find in order to reset your password."
+- **Make it scannable.** Write descriptive, task-stating headings ("Rotate an API key") not vague nouns ("Keys"). A reader scanning the table of contents should predict exactly what each page contains.
+- **Progressive disclosure.** Keep the common case in the main flow; push rare cases, flags, and caveats into collapsible sections, footnotes, or linked pages. Don't tax the 90% to serve the 10%.
+- **Parallel structure.** Sibling sections should share shape. Every API method page: Description → Parameters → Returns → Errors → Example. Predictability lets readers navigate by muscle memory.
+- **Link deliberately.** Link the first mention of a concept to its explanation. Don't bury a required prerequisite as an inline mid-sentence link: call it out as a prerequisite block so it cannot be missed.
+
+**Worked example.** A page titled "Configuration" that dumps 40 settings alphabetically forces every reader to scan all of them. Restructure: lead with the 3 settings 90% of users change, in a short "Common configuration" section; move the full list to a reference table below or on a linked page; give each setting a task-oriented sub-heading where relevant ("Increase the request timeout").
+
+**Checklist for a doc set:**
+- Can a reader find the right page in one guess from the nav?
+- Does each page declare its audience and prerequisites?
+- Is there exactly one canonical page per topic (no competing half-answers)?
+- Does every page front-load its most important information?
+- Are sibling pages structurally parallel?
+
+Good architecture is invisible: the reader lands on the right page, sees the answer at the top, and leaves. Bad architecture makes readers hunt, and hunting readers file support tickets or give up.
+
+---
+<!-- module: 05-style-clarity.md -->
+
+# Style & Clarity Rules
+
+Concrete, enforceable rules, not "write clearly."
+
+1. **Second person, imperative, active voice.** "Run `npm install`," not "The user should run" or "npm install is run." Address the reader as "you."
+2. **Present tense** for behavior. "The endpoint returns 200," not "will return."
+3. **One instruction per numbered step.** If a step contains "and," consider splitting. Number sequential actions; bullet unordered options.
+4. **Lead sentences with the point.** Put the keyword first so scanners catch it: "To reset your password, open Settings" beats the reverse.
+5. **Cut hedges and filler.** Delete "simply," "just," "easy," "obviously," "of course": they shame stuck readers and add nothing. Replace "in order to" → "to," "at this point in time" → "now," "utilize" → "use."
+6. **Define each term on first use, then use it consistently.** Never call one thing "app," "service," and "instance" across three paragraphs. One term per concept.
+7. **Format for meaning.** Code, filenames, commands, and literal UI labels in monospace; UI navigation in **bold**. Never wrap prose in code font for emphasis.
+8. **Show, then tell.** Pair every abstract instruction with a concrete example. A working snippet is worth three sentences of description.
+9. **Prefer specifics over vagueness.** "Wait about 30 seconds" beats "wait a while." "Returns up to 100 items" beats "returns several."
+
+**Before/after:** *"It should be noted that in order to utilize the API, users will need to first obtain an authentication token."* → *"To use the API, first get an auth token."* (24 words → 9, identical meaning.)
+
+**More edits:**
+- "This functionality provides users with the ability to filter." → "You can filter results."
+- "The system will automatically perform validation of the input." → "The system validates the input."
+- "In the event that the request fails..." → "If the request fails..."
+
+**Write for a global audience.** Short sentences, common words, no region-specific slang or idioms. Spell out ambiguous dates (2026-07-05, not 07/05/26). Enforce one style guide (capitalization, Oxford comma, product name) so the whole doc set reads as one voice.
+
+Above all: **accuracy beats polish.** An inaccurate doc is worse than none: it destroys trust in the entire doc set. Test every command and code sample before publishing.
+
+---
+<!-- module: 06-breaking-changes-migrations.md -->
+
+# Writing About Breaking Changes & Migrations
+
+This is where docs most often fail users, and where care matters most. A breaking change poorly documented turns into hours of user debugging and a flood of support requests.
+
+**Rules:**
+- **Announce loudly and early.** Breaking changes get a prominent, unmissable callout in release notes, not a buried bullet. State the exact version where the break lands.
+- **Say what breaks, and for whom.** "If you call `parse()` with a string, it now throws": name the exact API, the exact condition, and who is affected. A reader should determine in seconds whether they are impacted.
+- **Always give the migration path.** A breaking change without a migration guide is a broken promise. Provide before/after code side by side. If migration can be automated (codemod, script), lead with that.
+- **Explain the why, briefly.** One sentence of rationale reduces anger and support load: "We changed this to prevent silent data loss."
+- **State deprecation timelines.** Deprecated ≠ removed. Give the deprecation version, the planned removal version, and the recommended replacement. Keep deprecation warnings in the docs until removal is complete.
+
+**Migration guide skeleton:**
+1. *What changed*
+2. *Who is affected*
+3. *Before / after examples*
+4. *Step-by-step migration*
+5. *How to verify you migrated correctly*
+6. *Rollback / fallback if it goes wrong*
+
+**Worked micro-example (a release-note callout):**
+> **Breaking (v3.0):** `client.fetch()` no longer accepts a callback. Passing a function as the second argument now throws `TypeError`.
+> **Migrate:** `client.fetch(url, cb)` → `client.fetch(url).then(cb)`. See the [async migration guide].
+
+**Deprecation example:**
+> **Deprecated (v2.4):** `config.legacyMode` is deprecated and will be removed in v4.0. Use `config.compatibility` instead. Calls still work in v2.x and v3.x but log a warning.
+
+Common failures to avoid: listing a breaking change with no fix; using vague language ("some APIs have changed") instead of naming them; removing something that was never formally deprecated; or hiding the break inside a long changelog where impacted users scroll past it. Every breaking change should be findable, understandable, and actionable within a minute of a reader landing on the release notes.
+
+---
+<!-- module: 07-troubleshooting-security.md -->
+
+# Troubleshooting & Security Docs
+
+**Troubleshooting** is organized by *symptom*, not by cause: the reader knows what they see, not why it happens. Structure each entry:
+
+1. **Symptom**: the exact error message or observed behavior, quoted verbatim so it is searchable.
+2. **Cause**: what produces it.
+3. **Fix**: the steps to resolve it.
+4. **Confirm**: how to verify it is actually fixed.
+
+Include the literal error text; users paste error strings into search engines and your page's search box. Order entries by frequency (most common first). Add a "still stuck?" escape hatch: where to file an issue and which diagnostics (logs, version, config) to attach.
+
+**Worked example:**
+> **Symptom:** `Error: ECONNREFUSED 127.0.0.1:5432`
+> **Cause:** The database isn't running, or the port is wrong.
+> **Fix:** Start the database (`docker compose up db`) and confirm `DB_PORT` matches. **Confirm:** `psql -h localhost -p 5432` connects.
+
+**Security documentation** demands extra precision, because mistakes here are costly:
+- Be explicit and unambiguous: no "should probably." State exactly what is and isn't protected.
+- **Never show real secrets, tokens, or private keys.** Use obvious placeholders (`YOUR_API_KEY`, `sk_test_...`). Warn readers against committing secrets to version control.
+- Document the secure default, and clearly flag any insecure convenience option ("do not use in production").
+- Separate "how to configure securely" (a how-to) from "our security model / threat model" (an explanation).
+- Give a responsible-disclosure contact and a supported-versions policy.
+- State the blast radius of permissions and tokens: their scope, lifetime, and how to revoke them.
+
+**Common failures:** troubleshooting organized by internal component instead of user-visible symptom (readers can't map their error to your architecture); paraphrased error messages that don't match what users actually see; security examples containing real-looking keys that get copy-pasted into production; and vague hedging ("this is generally secure") that leaves the reader unable to make a safe decision. Precision and searchability are the whole game in both doc types.
+
+---
+<!-- module: 08-faq-voice-tone.md -->
+
+# FAQ Design, Voice & Tone
+
+## FAQ design
+
+FAQs are a last resort and a symptom, not a strategy. A "frequently asked question" usually means the primary docs failed to answer it in the right place: the durable fix is to answer it *there*, on the relevant page. Use an FAQ only for genuinely cross-cutting questions that don't belong to any single page: licensing, pricing, "is X supported," "how does this compare to Y."
+
+Rules:
+- Phrase each entry as the reader's *actual question in their words* ("Can I use this offline?"), not marketing framing ("Does our robust platform support disconnected operation?").
+- Keep answers short and link to the authoritative page rather than duplicating content.
+- Group by theme; order by frequency.
+- Prune ruthlessly. If an FAQ grows past ~15 entries, the underlying docs need restructuring, not a longer FAQ.
+- Never let the FAQ become the only place a fact lives: that fact belongs on a real page.
+
+## Voice and tone
+
+**Voice** is constant: your product's personality. **Tone** flexes with the reader's emotional state. Calibrate tone to context:
+- Routine how-to: neutral, efficient, confident.
+- Error messages and troubleshooting: calm, blame-free, helpful, never cute when a user is frustrated. No jokes on error pages.
+- Onboarding: warmer, more encouraging.
+
+**Worked example (same information, tone tuned to context):**
+- Success/onboarding: "Nice. Your first deploy is live. Next, add a custom domain."
+- Error state: "The deploy failed because the build step exited with code 1. Check the build log below, then retry." (No "oops!", no exclamation, no blame on the user.)
+
+Universal rules: be respectful and inclusive (avoid "simply/just," avoid idioms that don't translate, avoid ableist or exclusionary metaphors). Be consistent: pick and enforce conventions in a style guide (capitalization, Oxford comma, "email" vs "e-mail," how you name the product). Write for a global audience with short sentences and common words, and spell out ambiguous dates (2026-07-05).
+
+The test: read your error and troubleshooting copy imagining the reader is stressed and behind schedule. If any word would irritate that reader (a "simply," a joke, a shrug), cut it. Tone failures do the most damage exactly when the reader most needs help.

package/assets/skills/authored/tech-writing/composable/INDEX.md

@@ -0,0 +1,12 @@
+# Technical & Product Writing: Composable Index
+
+Loading policy: read this menu, then load 00-core (if present) plus the minis relevant to your task. If most of this skill is relevant, load BUNDLE.md (or a matching presets/*.md) in one read instead.
+
+- **01-audience-analysis.md** - Identify reader, their job-to-be-done, expertise, and assumed knowledge. *Load when* starting any doc or deciding scope/depth.
+- **02-document-types.md** - Tutorial vs how-to vs reference vs explanation; picking the right one. *Load when* deciding what kind of doc to write or a page feels muddled.
+- **03-readme-quickstart-changelog.md** - Structure for READMEs, quickstarts, changelogs, and release notes. *Load when* writing any of these specific artifacts.
+- **04-information-architecture.md** - Page scoping, front-loading, scannability, progressive disclosure, linking. *Load when* organizing a page or doc set.
+- **05-style-clarity.md** - Concrete sentence-level rules; voice, tense, cutting filler, formatting. *Load when* drafting or editing prose.
+- **06-breaking-changes-migrations.md** - Announcing breaks, migration guides, deprecation timelines. *Load when* documenting a breaking change, upgrade, or deprecation.
+- **07-troubleshooting-security.md** - Symptom-first troubleshooting; precise, safe security docs. *Load when* writing troubleshooting, error, or security content.
+- **08-faq-voice-tone.md** - When FAQs are justified; calibrating voice vs tone. *Load when* designing an FAQ or setting tone/personality.

package/assets/skills/authored/tech-writing/composable/VERSION

@@ -0,0 +1 @@
+1.0.0

package/assets/skills/authored/tech-writing/composable/mini/01-audience-analysis.md

@@ -0,0 +1,26 @@
+---
+pairs-with:
+  - 02-document-types.md
+---
+
+# Audience Analysis & Job-to-be-Done
+
+Never write a doc until you can name three things: (a) the reader, (b) the task they are mid-way through, and (c) what "done" looks like for them. Documentation is read by people under load (mid-incident, mid-integration, mid-evaluation), not studied at leisure.
+
+Segment readers on three axes:
+
+- **Expertise**: novice vs. expert. Novices need concepts and orientation; experts need a searchable reference and copy-paste snippets. Do not force an expert through a tutorial to find one flag name.
+- **Goal**: evaluating (should I adopt this?), integrating (make it work now), operating (keep it running), debugging (why did it break?). Each goal wants a different document type and depth.
+- **Context of use**: at a terminal, on a phone mid-incident, in a procurement meeting. Context dictates length, scannability, and where the answer must appear.
+
+**Worked example.** "How do I authenticate?" comes from at least two readers. The evaluator wants to know *which* auth methods exist and their tradeoffs: one paragraph and a table. The integrator wants a working request *right now*: a labeled code block with a real-looking token. Answer both, in that order, and label each so readers skip to their part.
+
+**State assumed prior knowledge explicitly at the top**: "This guide assumes a running cluster and kubectl configured." Unstated assumptions are the single largest cause of doc failure: the reader hits an undocumented prerequisite, gets stuck, and blames the product.
+
+Practical habits:
+- Write a one-line reader statement before drafting: "For an integrator who already has an API key and wants their first successful call."
+- List prerequisites as an up-front checklist, not scattered inline.
+- When a page must serve two audiences, split it into clearly labeled sections rather than blending. Blended docs frustrate both readers at once.
+- Prefer specifics the reader can check ("you need Node 18+") over vague reassurance ("recent Node").
+
+The audience decision drives every later choice: document type, structure, tone, and how much you explain versus assume. Get it wrong and even flawless prose fails, because it answers a question the reader did not ask.

package/assets/skills/authored/tech-writing/composable/mini/02-document-types.md

@@ -0,0 +1,27 @@
+---
+pairs-with:
+  - 04-information-architecture.md
+---
+
+# Choosing the Right Document Type
+
+Reader goals map to four distinct, non-interchangeable document types. Mixing them in one page is the most common structural mistake in documentation.
+
+- **Tutorial** (learning-oriented): a guided, guaranteed-to-succeed lesson for a newcomer. Linear, opinionated, one happy path, no alternatives, no error branches. Success = the reader built something and feels competent.
+- **How-to / task guide** (problem-oriented): steps to accomplish a specific real-world task the reader already knows they need. Assumes competence. May list variations. Success = task completed.
+- **Reference** (information-oriented): exhaustive, accurate description of the machinery: every parameter, return value, error code, config key. Dry, consistent, austere. Success = the reader found the exact fact and trusts it.
+- **Explanation / concept** (understanding-oriented): the *why*: architecture, tradeoffs, mental models. Read away from the keyboard. Success = the reader can reason about edge cases.
+
+Keep these separate. A reference page cluttered with tutorial hand-holding frustrates experts; a tutorial padded with reference tables loses novices. When a page feels muddled, it is usually two types fighting. Split it.
+
+**How to tell them apart in practice.** Ask what the reader is doing:
+- Learning the tool for the first time → tutorial.
+- Has a specific job to finish → how-to.
+- Needs a precise fact mid-work → reference.
+- Wants to understand tradeoffs before deciding → explanation.
+
+**Worked example.** "Authentication" often needs three pages, not one: a *tutorial* that walks a newcomer through their first authenticated call; a *reference* listing every auth method, scope, token lifetime, and error code; and an *explanation* of the auth model and its threat assumptions. One page trying to be all three serves none well.
+
+Signs you have mixed types: a tutorial with a giant parameter table; a reference page with encouraging asides ("Great, now let's..."); a how-to that pauses to explain architecture. Move the mismatched content to the page whose type it fits, and link between them.
+
+Parallel structure within a type helps: every API method reference page should share one shape (Description → Parameters → Returns → Errors → Example) so readers navigate by muscle memory.

package/assets/skills/authored/tech-writing/composable/mini/03-readme-quickstart-changelog.md

@@ -0,0 +1,22 @@
+---
+pairs-with:
+  - 06-breaking-changes-migrations.md
+---
+
+# README, Quickstart, Changelog & Release Notes
+
+**README**: a landing page and router, not a manual. Order: one-sentence description of what this is and who it is for; a short "why/what" paragraph; minimal install; a **60-second quickstart** that produces a visible result; then links out to deeper docs. Put the single most impressive working example above the fold. Badges and tables of contents come *after* value is demonstrated, not before. A reader should learn what the thing is and see it work within the first screen.
+
+**Quickstart**: the shortest path from zero to a first success, ideally under 5 minutes. List prerequisites up front as a checklist. Every step is copy-pasteable and idempotent where possible. End with a concrete checkpoint ("you should now see X") and exactly one clear next step. Cut every optional detail and link it instead; a quickstart that branches has failed at being quick.
+
+**Changelog vs release notes**: two artifacts for two audiences; do not conflate them.
+- A **changelog** is terse, chronological, developer-facing. Group entries per version as Added / Changed / Deprecated / Removed / Fixed / Security (the Keep a Changelog convention). Each entry is one line stating what changed.
+- **Release notes** are narrative and user-facing. Lead with the headline value ("Exports are now 10x faster"), explain impact, and call out breaking changes prominently.
+
+Both must be **newest first, dated, with a stable version identifier**. Never make a reader diff two versions to discover what changed. That is the changelog's entire job.
+
+**Worked example (a changelog entry vs a release note for the same change):**
+- Changelog: `### Changed` / `- \`export()\` now streams results instead of buffering (#412).`
+- Release note: "Large exports no longer run out of memory. `export()` now streams, so multi-gigabyte reports complete reliably. No code change needed unless you relied on the full result being in memory at once (see [migration])."
+
+Common failures: a README that explains philosophy before showing the tool work; a quickstart padded with configuration options; release notes that bury a breaking change in a bullet list. Fix each by ruthlessly front-loading the reader's payoff and pushing detail to linked reference pages.

package/assets/skills/authored/tech-writing/composable/mini/04-information-architecture.md

@@ -0,0 +1,21 @@
+# Information Architecture
+
+How to structure pages and doc sets so readers find and consume the right thing fast.
+
+- **One page, one job.** If a page answers more than one reader question, split it. Competing half-answers on multiple pages are worse than one canonical page. Ensure exactly one authoritative page per topic.
+- **Front-load the answer.** Use the inverted pyramid: conclusion or result first, then detail, then background. Readers scan the first line of each section and bail early, so the payoff must come first. "To reset your password, open Settings" beats "Open Settings, which you can find in order to reset your password."
+- **Make it scannable.** Write descriptive, task-stating headings ("Rotate an API key") not vague nouns ("Keys"). A reader scanning the table of contents should predict exactly what each page contains.
+- **Progressive disclosure.** Keep the common case in the main flow; push rare cases, flags, and caveats into collapsible sections, footnotes, or linked pages. Don't tax the 90% to serve the 10%.
+- **Parallel structure.** Sibling sections should share shape. Every API method page: Description → Parameters → Returns → Errors → Example. Predictability lets readers navigate by muscle memory.
+- **Link deliberately.** Link the first mention of a concept to its explanation. Don't bury a required prerequisite as an inline mid-sentence link: call it out as a prerequisite block so it cannot be missed.
+
+**Worked example.** A page titled "Configuration" that dumps 40 settings alphabetically forces every reader to scan all of them. Restructure: lead with the 3 settings 90% of users change, in a short "Common configuration" section; move the full list to a reference table below or on a linked page; give each setting a task-oriented sub-heading where relevant ("Increase the request timeout").
+
+**Checklist for a doc set:**
+- Can a reader find the right page in one guess from the nav?
+- Does each page declare its audience and prerequisites?
+- Is there exactly one canonical page per topic (no competing half-answers)?
+- Does every page front-load its most important information?
+- Are sibling pages structurally parallel?
+
+Good architecture is invisible: the reader lands on the right page, sees the answer at the top, and leaves. Bad architecture makes readers hunt, and hunting readers file support tickets or give up.

package/assets/skills/authored/tech-writing/composable/mini/05-style-clarity.md

@@ -0,0 +1,29 @@
+---
+pairs-with:
+  - 08-faq-voice-tone.md
+---
+
+# Style & Clarity Rules
+
+Concrete, enforceable rules, not "write clearly."
+
+1. **Second person, imperative, active voice.** "Run `npm install`," not "The user should run" or "npm install is run." Address the reader as "you."
+2. **Present tense** for behavior. "The endpoint returns 200," not "will return."
+3. **One instruction per numbered step.** If a step contains "and," consider splitting. Number sequential actions; bullet unordered options.
+4. **Lead sentences with the point.** Put the keyword first so scanners catch it: "To reset your password, open Settings" beats the reverse.
+5. **Cut hedges and filler.** Delete "simply," "just," "easy," "obviously," "of course": they shame stuck readers and add nothing. Replace "in order to" → "to," "at this point in time" → "now," "utilize" → "use."
+6. **Define each term on first use, then use it consistently.** Never call one thing "app," "service," and "instance" across three paragraphs. One term per concept.
+7. **Format for meaning.** Code, filenames, commands, and literal UI labels in monospace; UI navigation in **bold**. Never wrap prose in code font for emphasis.
+8. **Show, then tell.** Pair every abstract instruction with a concrete example. A working snippet is worth three sentences of description.
+9. **Prefer specifics over vagueness.** "Wait about 30 seconds" beats "wait a while." "Returns up to 100 items" beats "returns several."
+
+**Before/after:** *"It should be noted that in order to utilize the API, users will need to first obtain an authentication token."* → *"To use the API, first get an auth token."* (24 words → 9, identical meaning.)
+
+**More edits:**
+- "This functionality provides users with the ability to filter." → "You can filter results."
+- "The system will automatically perform validation of the input." → "The system validates the input."
+- "In the event that the request fails..." → "If the request fails..."
+
+**Write for a global audience.** Short sentences, common words, no region-specific slang or idioms. Spell out ambiguous dates (2026-07-05, not 07/05/26). Enforce one style guide (capitalization, Oxford comma, product name) so the whole doc set reads as one voice.
+
+Above all: **accuracy beats polish.** An inaccurate doc is worse than none: it destroys trust in the entire doc set. Test every command and code sample before publishing.

package/assets/skills/authored/tech-writing/composable/mini/06-breaking-changes-migrations.md

@@ -0,0 +1,33 @@
+---
+pairs-with:
+  - 03-readme-quickstart-changelog.md
+  - code-review/07-api-design.md
+---
+
+# Writing About Breaking Changes & Migrations
+
+This is where docs most often fail users, and where care matters most. A breaking change poorly documented turns into hours of user debugging and a flood of support requests.
+
+**Rules:**
+- **Announce loudly and early.** Breaking changes get a prominent, unmissable callout in release notes, not a buried bullet. State the exact version where the break lands.
+- **Say what breaks, and for whom.** "If you call `parse()` with a string, it now throws": name the exact API, the exact condition, and who is affected. A reader should determine in seconds whether they are impacted.
+- **Always give the migration path.** A breaking change without a migration guide is a broken promise. Provide before/after code side by side. If migration can be automated (codemod, script), lead with that.
+- **Explain the why, briefly.** One sentence of rationale reduces anger and support load: "We changed this to prevent silent data loss."
+- **State deprecation timelines.** Deprecated ≠ removed. Give the deprecation version, the planned removal version, and the recommended replacement. Keep deprecation warnings in the docs until removal is complete.
+
+**Migration guide skeleton:**
+1. *What changed*
+2. *Who is affected*
+3. *Before / after examples*
+4. *Step-by-step migration*
+5. *How to verify you migrated correctly*
+6. *Rollback / fallback if it goes wrong*
+
+**Worked micro-example (a release-note callout):**
+> **Breaking (v3.0):** `client.fetch()` no longer accepts a callback. Passing a function as the second argument now throws `TypeError`.
+> **Migrate:** `client.fetch(url, cb)` → `client.fetch(url).then(cb)`. See the [async migration guide].
+
+**Deprecation example:**
+> **Deprecated (v2.4):** `config.legacyMode` is deprecated and will be removed in v4.0. Use `config.compatibility` instead. Calls still work in v2.x and v3.x but log a warning.
+
+Common failures to avoid: listing a breaking change with no fix; using vague language ("some APIs have changed") instead of naming them; removing something that was never formally deprecated; or hiding the break inside a long changelog where impacted users scroll past it. Every breaking change should be findable, understandable, and actionable within a minute of a reader landing on the release notes.

package/assets/skills/authored/tech-writing/composable/mini/07-troubleshooting-security.md

@@ -0,0 +1,30 @@
+---
+pairs-with:
+  - code-review/02-security-review.md
+---
+
+# Troubleshooting & Security Docs
+
+**Troubleshooting** is organized by *symptom*, not by cause: the reader knows what they see, not why it happens. Structure each entry:
+
+1. **Symptom**: the exact error message or observed behavior, quoted verbatim so it is searchable.
+2. **Cause**: what produces it.
+3. **Fix**: the steps to resolve it.
+4. **Confirm**: how to verify it is actually fixed.
+
+Include the literal error text; users paste error strings into search engines and your page's search box. Order entries by frequency (most common first). Add a "still stuck?" escape hatch: where to file an issue and which diagnostics (logs, version, config) to attach.
+
+**Worked example:**
+> **Symptom:** `Error: ECONNREFUSED 127.0.0.1:5432`
+> **Cause:** The database isn't running, or the port is wrong.
+> **Fix:** Start the database (`docker compose up db`) and confirm `DB_PORT` matches. **Confirm:** `psql -h localhost -p 5432` connects.
+
+**Security documentation** demands extra precision, because mistakes here are costly:
+- Be explicit and unambiguous: no "should probably." State exactly what is and isn't protected.
+- **Never show real secrets, tokens, or private keys.** Use obvious placeholders (`YOUR_API_KEY`, `sk_test_...`). Warn readers against committing secrets to version control.
+- Document the secure default, and clearly flag any insecure convenience option ("do not use in production").
+- Separate "how to configure securely" (a how-to) from "our security model / threat model" (an explanation).
+- Give a responsible-disclosure contact and a supported-versions policy.
+- State the blast radius of permissions and tokens: their scope, lifetime, and how to revoke them.
+
+**Common failures:** troubleshooting organized by internal component instead of user-visible symptom (readers can't map their error to your architecture); paraphrased error messages that don't match what users actually see; security examples containing real-looking keys that get copy-pasted into production; and vague hedging ("this is generally secure") that leaves the reader unable to make a safe decision. Precision and searchability are the whole game in both doc types.