@jaybeeuu/agent-cortex 1.20.0

package/skills/review/refactor-skill/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: refactor-skill
+description: Refactor an existing SKILL.md to the canonical anatomy template through template comparison, user interview, and one-pass rewrite. Use when refactoring, restructuring, or reviewing skills, or comparing a skill to the current template.
+---
+
+# Refactor Skill
+
+## When to use
+
+- A skill's SKILL.md predates the anatomy template and needs upgrading.
+- You want to align a skill with `docs/skills/skill-anatomy.md` before the refactor wave touches it.
+- You want to compare a skill's structure to the current template standard.
+- Trigger phrases: "refactor this skill", "restructure this skill", "review this skill", "upgrade X to the template", "align with anatomy".
+
+## When NOT to use
+
+- Creating a brand-new skill from scratch — use `write-a-skill` instead.
+- Minor copy-editing or typo fixes that don't need anatomy alignment.
+- Skills that are already verified against the anatomy template.
+
+## Workflow
+
+### 1. Gather materials
+
+Read the target skill's `skills/<name>/SKILL.md` and the canonical anatomy reference:
+
+```bash
+cat skills/<name>/SKILL.md
+cat docs/skills/skill-anatomy.md
+```
+
+If the target has no `SKILL.md` yet, abort — this skill upgrades existing files; use `write-a-skill` for new creation.
+
+### 2. Compare against the template
+
+Run through each dimension of the anatomy template and record how the target currently relates to it. For each dimension, note the current state — whether it's present, missing, partial, or needs adjustment:
+
+- **Front matter**: `name` and `description` present? Description follows the two-sentence format (capability statement + `Use when ...` with 2-4 trigger phrases)?
+- **When to use**: present? Trigger phrases included?
+- **When NOT to use**: present? When to include vs omit? Only include if the skill has similar neighbours where invocation precision matters.
+- **Workflow**: ordered deterministic steps with observable outcomes?
+- **Red Flags**: present? Only include for discipline-enforcement skills (security, TDD, review).
+- **Common Rationalizations**: present? Only include for process-critical skills where shortcut pressure is common.
+- **Phase-gate checklists**: present? Only include for multi-phase workflows (3+ distinct phases).
+- **Cross-skill references**: present? Only include when another skill owns a sub-domain better than restating.
+- **Examples**: present? Only include for non-trivial output contracts.
+- **Verification checklist**: present? Concrete, machine-checkable items?
+- **Voice/tone**: imperative second-person? Positive framing? Rationale sentences for non-obvious rules?
+- **Line length**: near ~150 lines? Under 150 hard cap?
+
+The framing is **comparison, not gap detection** — a dimension may already be fully aligned. Build a structured assessment grouped by required vs optional. See `EXAMPLES.md` for the output shape.
+
+#### Phase gate: comparison complete
+
+- [ ] Required dimensions checked (front matter, When to use, Workflow, Verification checklist)
+- [ ] Optional dimensions noted as relevant or not for this skill
+- [ ] You can articulate what will change and what will stay the same
+
+### 3. Present findings and propose changes
+
+Share the full comparison assessment with the user. Do not start editing yet — this step is about understanding and agreement.
+
+Present the comparison and discuss optional sections using the inclusion criteria below. For opted-in sections, capture content requirements; for opted-out, record the decision. Do not ask about required sections (When to use, Workflow, Verification checklist).
+
+| Section | Ask if |
+|---|---|
+| `When NOT to use` | The skill has similar neighbours where invocation precision matters |
+| `Red Flags` | The skill enforces process discipline (security, TDD, review) |
+| `Common Rationalizations` | The skill is process-critical where shortcut pressure is common |
+| `Phase-gate checklists` | The workflow has 3+ distinct phases |
+| `Cross-skill references` | Another skill owns a sub-domain the workflow delegates to |
+| `Examples` | The output contract is non-trivial (formats, schemas, templates) |
+| `Philosophy / rationale` | The skill defends an opinionated method with trade-offs |
+
+Then **propose the plan**: summarise what will change, what will stay the same, and the proposed new description. Ask for explicit approval before any file is written — iterate on the proposal if needed.
+
+#### Phase gate: plan approved
+
+- [ ] Comparison and optional-section discussion presented
+- [ ] Proposed changes + new description shown to user
+- [ ] User explicitly approved the plan
+
+### 4. Produce the rewrite
+
+Write the complete new `skills/<name>/SKILL.md` in one pass covering:
+
+- Correct front matter
+- All required sections in canonical order
+- Each opted-in optional section with its what/when/example guidance inline
+- Voice and tone per `style-code` (imperative second-person, positive framing, rationale sentences)
+- Description matching the two-sentence format with 2-4 trigger phrases
+
+Write the file directly:
+
+```bash
+cat > skills/<name>/SKILL.md << 'EOF'
+<new content>
+EOF
+```
+
+### 5. Validate against template constraints
+
+After writing, verify:
+
+- [ ] Front matter has `name` and `description`
+- [ ] Description is ≤ 1024 chars, two sentences, second starts with "Use when"
+- [ ] Required sections present: `## When to use`, `## Workflow`, `## Verification checklist`
+- [ ] All opted-in optional sections present in canonical order
+- [ ] `SKILL.md` ≤ 150 lines (`wc -l skills/<name>/SKILL.md`)
+- [ ] Body uses imperative second-person, positive framing
+- [ ] No ALL-CAPS emphasis
+- [ ] Rationale sentences present for non-obvious rules
+
+Report any validation failures and fix them. If all pass, summarise what was changed.
+
+## Examples
+
+See `EXAMPLES.md` for a worked comparison table showing the template-comparison output shape for a typical skill refactor.
+
+## Red Flags
+
+- **"I already know this skill"** — Reading the file fresh reveals assumptions that familiarity hides. A skill you use daily may still have front-matter omissions or tone drift. Always read it.
+- **Deciding optional sections without asking** — Optional sections depend on the skill's neighbours and purpose, which the user understands better than an agent. Making the call unilaterally produces a weaker result.
+- **Keeping old phrasing because "it was already fine"** — Voice and tone rules (imperative second-person, positive framing, rationale sentences) are hard to apply incrementally. Old phrasing that reads fine in isolation may break template consistency.
+- **Cargo-culting section headings** — Copying section headings from the template without adapting content to the skill's actual purpose creates generic, low-value sections. Each section must earn its place with specific, skill-relevant content.
+- **Refactoring for its own sake** — If the comparison shows the skill is already well-aligned, don't change it. Adding churn for its own sake degrades clarity and wastes time. Report that no changes are needed and stop.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This skill is already close enough — I'll just tweak a few lines" | Partial alignment creates drift. The template enforces section ordering, tone, and description rules that are hard to apply incrementally. Do the full pass. |
+| "The comparison takes too long — I can spot the issues from reading" | The comparison checklist ensures nothing is missed. Skipping it trades thoroughness for speed and usually misses something. |
+| "I know what optional sections they'll want" | You might be right, but the user still needs to confirm. Presenting a recommendation with your reasoning is fine — deciding without asking isn't. |
+
+## Verification checklist
+
+- [ ] Target skill's `SKILL.md` exists and was read
+- [ ] Template comparison completed before any rewrite
+- [ ] Phase gates passed: comparison complete, plan approved
+- [ ] User interviewed on every optional section and approved the plan
+- [ ] Rewrite includes all required sections in canonical order
+- [ ] Rewrite includes opted-in optional sections with guidance
+- [ ] Description follows two-sentence format with trigger phrases
+- [ ] `SKILL.md` ≤ 150 lines
+- [ ] Voice/tone matches `style-code` / `style-documentation` standards
+- [ ] No red flags triggered during execution
+- [ ] Validation completed and all checks pass

package/skills/review/review-security/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: review-security
+description: Scans git changes for leaked secrets, credentials, and tokens using gitleaks. Use when you need to "check for secrets", "scan for credentials", or "review security" before committing.
+---
+
+# Review Security
+
+## When to use
+
+- Before any commit — scan staged changes for secrets.
+- During code review — scan the most recent commit.
+- Asked to "check for secrets", "scan for credentials", or "review security".
+
+## When NOT to use
+
+- Auditing dependency vulnerabilities or supply-chain security — gitleaks scans your code, not your dependencies.
+- Reviewing authentication or authorisation logic — use a manual code review instead.
+- Scanning an entire repository history for the first time — run `gitleaks detect --full` separately; this skill is for incremental scans.
+
+## Philosophy / rationale
+
+- **Automated scanning catches what manual review misses.** A secret committed to git is there forever — even if you remove it later, it lives in history.
+- **Staged scans are the cheapest catch point.** Scanning before commit costs seconds. Cleaning up after a push costs hours and involves the whole team.
+- **Gitleaks runs locally without sending code to a third party.** Your code never leaves your machine.
+
+## Workflow
+
+### 1. Verify gitleaks is installed
+
+```bash
+gitleaks version
+```
+
+If the command fails, gitleaks is not installed. Inform the user and offer to install it:
+
+```bash
+bash "$(find ~ -path '*/agent-cortex/skills/review-security/scripts/install-gitleaks.sh' 2>/dev/null | head -1)"
+```
+
+### 2. Determine the scan scope
+
+| Situation | Command |
+|---|---|
+| Staged changes (before committing) | `gitleaks protect --staged -v` |
+| Most recent commit (after committing, e.g. during review) | `gitleaks detect --log-opts "HEAD~1..HEAD" -v` |
+| Specific ref range | `gitleaks detect --log-opts "<from>..<to>" -v` |
+
+### 3. Run the scan and interpret the verdict
+
+- Exit `0` — **PASS**. No secrets found. Proceed.
+- Exit `1` — **FAIL**. Findings are printed with file, line, and rule name.
+
+### 4. Handle failures
+
+If the verdict is FAIL, report each finding as a required change. Do not proceed until secrets are removed.
+
+When running within a ralph review pipeline, the outcome is communicated through the `---REPORT---` block that ralph parses — set `REVIEW_OUTCOME: CHANGES_REQUESTED` in that block and list each finding under `CHANGES_REQUESTED` (see the review template at `skills/create-task/templates/review.md`).
+
+## Red Flags
+
+- **Skipping the scan because "it is just documentation".** Secrets leak in docs, config examples, and READMEs just as easily as in code.
+- **Dismissing a finding without verifying.** Always check the context before marking a finding as a false positive.
+- **Scanning after pushing instead of before.** Once pushed, the secret is on the remote. Even a force push may not fully remove it from history.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I will check for secrets manually" | Manual review has blind spots. Gitleaks catches patterns you will scroll past. |
+| "This is just a config file" | Config files are where secrets most commonly live. |
+| "I will scan before pushing, not before committing" | The earlier you catch it, the cheaper it is. Pre-commit scan costs two seconds. |
+| "This is a false positive" | It might be. Verify the context before dismissing it. |
+
+## Cross-skill references
+
+| When you need… | Use this skill |
+|---|---|
+| Code conventions that help avoid embedding secrets | `style-code` |
+| Documentation conventions that keep examples secret-free | `style-documentation` |
+
+## Examples
+
+### Reading a FAIL finding
+
+```
+Finding:     detected AWS Access Key ID
+Rule:        aws-access-key-id
+File:        deploy/config.ts
+Line:        42
+Secret:      AKIA************
+```
+
+Each finding includes the rule that caught it, the file and line, and the matched secret. Investigate to confirm or dismiss.
+
+### Staged scan catches before it is too late
+
+| Instead of… | Write… |
+|---|---|
+| Committing `config.ts` with a hardcoded API key, pushing, then realising | Running `gitleaks protect --staged` before commit, catching the key in the staged diff |
+
+## Verification checklist
+
+- [ ] Gitleaks is installed and available
+- [ ] Appropriate scan scope selected (staged, commit, or ref range)
+- [ ] Scan run and verdict recorded
+- [ ] Every FAIL finding investigated and resolved
+- [ ] No commit pushed with unresolved secrets

package/skills/review/review-security/scripts/install-gitleaks.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Installs gitleaks using the appropriate method for the current platform.
+set -euo pipefail
+
+if command -v gitleaks &>/dev/null; then
+  echo "gitleaks is already installed: $(gitleaks version)"
+  exit 0
+fi
+
+OS="$(uname -s)"
+
+if [ "$OS" = "Darwin" ]; then
+  if command -v brew &>/dev/null; then
+    echo "Installing gitleaks via Homebrew..."
+    brew install gitleaks
+  else
+    echo "Homebrew not found. Install it from https://brew.sh, then run: brew install gitleaks"
+    exit 1
+  fi
+elif [ "$OS" = "Linux" ]; then
+  echo "Downloading latest gitleaks release from GitHub..."
+  LATEST=$(curl -s https://api.github.com/repos/gitleaks/gitleaks/releases/latest \
+    | grep '"tag_name"' | cut -d'"' -f4)
+  ARCH="$(uname -m)"
+  case "$ARCH" in
+    x86_64) ARCH="x64" ;;
+    aarch64|arm64) ARCH="arm64" ;;
+    *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
+  esac
+  INSTALL_DIR="${HOME}/.local/bin"
+  mkdir -p "$INSTALL_DIR"
+  URL="https://github.com/gitleaks/gitleaks/releases/download/${LATEST}/gitleaks_${LATEST#v}_linux_${ARCH}.tar.gz"
+  curl -sL "$URL" | tar -xz -C "$INSTALL_DIR" gitleaks
+  chmod +x "$INSTALL_DIR/gitleaks"
+  if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
+    echo "Note: add $INSTALL_DIR to your PATH if gitleaks is not found after install."
+  fi
+else
+  echo "Unsupported OS: $OS. See https://github.com/gitleaks/gitleaks#installing for manual install instructions."
+  exit 1
+fi
+
+echo "Installed: $(gitleaks version)"

package/skills/style/style-code/REFERENCE.md

@@ -0,0 +1,38 @@
+# Additional Examples
+
+Extended before/after pairs for less common style-code patterns.
+
+## Validation and error handling
+
+| Instead of… | Write… |
+|---|---|
+| ```ts function process(input: any) { // assume it's correct } ``` | ```ts function process(input: unknown): ProcessResult { const data = parseInput(input); // validated at system edge } ``` |
+| ```ts throw "invalid"; ``` | ```ts throw new ValidationError({ field: "email", reason: "missing @" }); ``` |
+
+## Module structure
+
+| Instead of… | Write… |
+|---|---|
+| `actions/`, `reducers/`, `selectors/`, `thunks/` — grouped by technical type | `accounts/`, `payments/`, `notifications/` — each with its own types, actions, reducers, selectors, thunks |
+| `utils/` with fifty unrelated helpers | Feature-specific modules (`accounts/resolve-overdue.ts`, `accounts/export-csv.ts`) |
+| `shared/types.ts` with every type | Types co-located in the owning package, exported from `index.ts` |
+
+## State management
+
+| Instead of… | Write… |
+|---|---|
+| ```ts let count = 0; function inc() { count++; } ``` (shared mutable state) | ```ts const [count, setCount] = useState(0); // explicit, local, testable ``` |
+| Async state stored as separate booleans | ```ts type AsyncState<T> = { status: "idle" \| "loading" \| "success"; data?: T; error?: Error }; ``` |
+
+## Component structure
+
+| Instead of… | Write… |
+|---|---|
+| ```ts function Page() { const [data, setData] = useState(null); useEffect(...); return <div>...</div>; } ``` (data loading + rendering) | Split into `usePageData()` hook and `Page` component with explicit props |
+
+## Public API conventions
+
+| Instead of… | Write… |
+|---|---|
+| Default export from module | Named exports from `index.ts` for the intended public API |
+| ```ts export function x(a, b, c) { ... } ``` with undocumented params | ```ts export function createReport(options: ReportOptions): Report { ... } ``` with documented `ReportOptions` interface |

package/skills/style/style-code/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: style-code
+description: Defines this project's coding style, conventions, and architectural preferences (naming, module boundaries, structure). Use BEFORE writing or editing any code and during any refactor or code review — consult it whenever you add or change functions, modules, types, or files rather than choosing style ad hoc. Also for a "style review", "naming conventions", or "module boundaries".
+---
+
+# Code Style
+
+## When to use
+
+- Writing new code, editing existing code, or reviewing a pull request.
+- Deciding between type approaches, naming strategies, or module boundaries.
+- Asked for a "style review", "does this look right", or "what's the convention here".
+
+## When NOT to use
+
+- Writing tests or deciding test strategy — use `style-tests` or `tdd` instead.
+- Communication tone, document structure, or external writing — use `style-comms`.
+- Deciding what and whether to document — use `style-documentation`.
+
+## Philosophy / rationale
+
+- **Small, focused changes beat broad refactors.** Every change should answer one question. Scope creep is the most common source of defects in an otherwise clean change.
+- **Clarity over cleverness.** Code is read many more times than it is written. Clever code optimises for the writing moment; clear code optimises for every subsequent reading.
+- **Validate at system edges, trust the type system within.** Inbound data from API ingress, deserialisation, or inter-service communication is untrusted until validated. Within application boundaries, trust the type system to enforce correct calls — don't re-validate at every internal module boundary.
+- **Prefer result objects for domain errors; reserve exceptions for emergencies.** Expected failures — validation errors, not-found, conflict — belong in a typed result the caller can handle. Thrown `Error` should signal something genuinely broken: a programming mistake, an invariant violation, or unrecoverable state.
+- **Deep modules beat shallow ones.** A tight public API with complexity hidden behind it is easier to use, test, and change than a flat sprawl of interdependent helpers.
+- **Abstraction must earn its keep, but local helpers are free.** An abstraction extracted into a shared module before its shape is proven nearly always guesses wrong. But extracting a local helper to clarify domain logic is always worthwhile — even at first use. The goal is readable code, not zero duplication.
+
+## Workflow
+
+1. **Orient.** Run the `tdd` skill for the red-green-refactor loop. Style rules guide the shape of the code you produce inside that loop.
+
+2. **Define types and boundaries first.** Model domain concepts with named types, interfaces, discriminated unions, or typed result objects. Keep types close to the service or package that owns them. Validate unknown data at system edges (API ingress, deserialisation, inter-service boundaries) using runtime validators — treat incoming data as `unknown` until checked. Within the application, trust the type system to enforce correct calls.
+
+3. **Name for clarity.** Use descriptive names drawn from the project's ubiquitous language. Do not invent synonyms for established domain terms. If the language isn't yet defined for this area, run `grill-with-docs` to extract it before naming. Use consistent suffixes: `Props`, `Options`, `Context`, `State` where they aid recognition. Name factories and builders with explicit verbs (`create`, `make`, `build`, `resolve`, `parse`, `compile`, `fetch`, `read`, `write`).
+
+4. **Structure with ownership in mind.** Keep ingress, processing, API, CLI, and infrastructure concerns in separate modules. Split modules when it sharpens bounded-context ownership; do not split just to reshuffle code.
+
+   **Co-locate by domain, not by technical type.** All the files for a given feature or bounded context — types, actions, reducers, selectors, thunks, components, tests — live alongside each other. Do not group files by what they *are* ("all selectors here, all thunks there"). Group them by what they *belong to* ("everything for the accounts domain here"). This keeps domain boundaries visible in the filesystem and makes it safe to rename, extract, or delete a feature without hunting across a dozen type-based directories.
+
+5. **Apply UI and state patterns.** Prefer small functional components with explicit props interfaces. Use CSS Modules when the stack supports them. Keep state transitions visible and predictable — encapsulate state behind hooks, selectors, or dedicated state modules. Keep derived state clearly separated from primitive state.
+
+6. **Review against the checklist below.** Read the diff once as its reviewer before committing.
+
+## Red Flags
+
+- **Reaching for `any` or non-null assertions.** Every `any` is a blind spot in the type system. If unavoidable, keep it narrow and function-scoped.
+- **Broadening scope.** A change that fixes a bug and also renames three modules and extracts an abstraction is three changes. Split it.
+- **Skipping edge validation.** Inbound data at API ingress, deserialisation, or inter-service boundaries is untrusted until validated. Within the application, trust the type system. A missed edge validation silently poisons downstream callers.
+- **Unstructured errors.** A thrown string or `{ message }` object leaves the caller guessing what failed and why. Prefer typed result objects for expected domain failures — use thrown `Error` only when something has genuinely gone wrong (programming error, invariant violation, unrecoverable state).
+- **Large modules with mixed concerns.** A file doing data loading, state orchestration, and rendering is three modules waiting to be extracted.
+- **Premature cross-module abstraction.** Extracting a shared utility into a common module before the pattern has proven itself across multiple callers nearly always guesses the wrong shape. Local helpers that clarify intent are fine at first use — keep them within the module boundary until the pattern repeats.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I'll just use `any` here — it's a small edge case" | Every `any` is a type system blind spot. If unavoidable, keep it narrow, local, and documented. |
+| "I'll clean this up in a follow-up" | Follow-ups rarely happen. Keep the change proportionate but correct. |
+| "This is too small for edge validation" | The smallest unvalidated input at a system edge causes the most confusing downstream failures. Validate incoming data once at the boundary and let the type system carry it from there. |
+| "I'll add types later" | Types are cheapest at write time. Adding them later is a refactor you will skip. |
+| "The existing code already does it this way" | Existing patterns may predate this guide. Follow the guide unless changing it would inflate scope beyond the task. |
+| "I'll throw an Error for this validation failure" | Expected domain failures should be typed results the caller can handle. Reserve thrown `Error` for things that are truly broken. |
+| "I'll extract this into a shared util — it might be useful later" | Extract locally first if it clarifies the code. Promote to shared only when at least a third real caller emerges. Guessing the shape before then wastes time and creates coupling. |
+
+## Cross-skill references
+
+| When you need… | Use this skill |
+|---|---|
+| Test-first development loop | `tdd` |
+| Test writing conventions | `style-tests` |
+| Building or hardening the project's ubiquitous language | `grill-with-docs` |
+| Communication tone and document structure | `style-comms` |
+| What and whether to document | `style-documentation` |
+| Surfacing architectural friction and deepening shallow modules | `improve-codebase-architecture` |
+| Secrets and credential scanning | `review-security` |
+
+## Examples
+
+See `REFERENCE.md` for the full set. The most common patterns:
+
+### Types at boundaries
+
+| Instead of… | Write… |
+|---|---|
+| `function handleRequest(raw: any) { ... }` with no validation | `function handleRequest(raw: unknown): HandlerResult { ... }` validated at the ingress boundary |
+| `const user = JSON.parse(raw)` with unchecked cast | `const user = parseUser(JSON.parse(raw))` validated with `parseUser` at the deserialisation edge |
+
+### Naming
+
+| Instead of… | Write… |
+|---|---|
+| `function process(items) { ... }` | `function resolveOverdueAccounts(accounts: Account[]) { ... }` |
+| `interface Config { ... }` | `interface ExportOptions { ... }` |
+
+### Scoping
+
+| Instead of… | Write… |
+|---|---|
+| One commit fixing a bug, renaming a module, and adding an abstraction | One commit per concern, each reviewable on its own |
+
+## Verification checklist
+
+- [ ] Change is focused on one concern — no scope creep
+- [ ] External inputs validated at system edges (API, deserialisation, inter-service)
+- [ ] Exported APIs and return types are explicit (no inferred `any`)
+- [ ] Names are descriptive and drawn from the project's ubiquitous language
+- [ ] No `any`, broad casts, or non-null assertions without narrow scoping
+- [ ] Types are co-located with the module that owns them
+- [ ] Modules are split by ownership, not just for reshuffling code
+- [ ] State transitions are explicit and encapsulated behind a clear API
+- [ ] Tests and docs updated where behaviour changed
+- [ ] Staged changes scanned with `review-security` before committing

package/skills/style/style-comms/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: style-comms
+description: Sets tone, structure, and concision rules for written communication. Use BEFORE composing project or external-facing text — commit messages, PR descriptions, tickets, RFCs, PRDs, proposals, reports, or status updates — and when asked to "make this clearer" or for a "style review".
+---
+
+# Communication Style
+
+## When to use
+
+- Writing a ticket, RFC, PRD, proposal, report, or any document someone else will read.
+- Reviewing a draft for tone, structure, or concision.
+- Asked for a "style review", "make this clearer", or "is this well written?".
+
+## When NOT to use
+
+- Deciding *whether and what* to document — use `style-documentation` instead.
+- Writing code or test code — use `style-code` or `style-tests` instead.
+
+## Philosophy / rationale
+
+- **Reader time is more valuable than writer time.** Every sentence you write costs the reader time to process. Make each one count.
+- **Lead with the payoff because the reader's first question is always "why am I reading this?".** Put the key takeaway — whether it's a decision, a conclusion, a recommendation, or a summary — up front so they orient before diving into detail.
+- **Triangular structure (broad → narrow) lets readers self-select depth.** A reader who only needs context stops early; one who needs specifics reads on. Both get what they need without friction.
+- **Explicit language ages better than hedged language.** Hedging ("might", "potentially", "it could be") lets each reader fill in their own interpretation — which will differ from yours.
+
+## Workflow
+
+1. **Identify the audience and the ask.** Who is reading this, and what do they need to decide or know by the end? Write the ask down first.
+
+2. **Lead with the payoff.** Open with the key takeaway — the decision needed, the conclusion reached, the recommendation, or a summary of findings.
+   - Informal documents: one or two sentence TL;DR.
+   - Formal documents: a summary of no more than two paragraphs covering purpose, key points, and conclusions.
+
+3. **Structure with the triangular approach.** Start broad, then narrow progressively — from context to problem to proposed approach to specific detail. Put the most granular information last.
+
+4. **Write with concision.** Every sentence must earn its place.
+   - Prefer plain language over formal or corporate phrasing.
+   - State things directly. Avoid hedging ("might", "potentially", "it could be said"), filler ("It is worth noting that…", "As mentioned above…"), and throat-clearing.
+   - Do not restate what was just said in different words.
+   - Do not open with a preamble that restates the document title or obvious context.
+
+5. **Use lists, links, and examples intentionally.**
+   - **Lists:** Use for genuinely enumerable, parallel items. Do not break a single flowing thought into bullets.
+   - **Links:** Link to the specific location (code line, document section), not a top-level root. Do not link things the reader can trivially find. Add a **References** section at the end only when multiple links need collating — inline a single link instead.
+   - **Examples:** Use to illustrate complex ideas — code blocks under 15 lines, calculations with workings, concrete scenarios. Remove if the surrounding prose is already clear. Show only what makes the point.
+
+6. **Review against the checklist below.** Read the draft once as its intended audience before sending or committing.
+
+## Examples
+
+### Lead with the payoff
+
+| Instead of… | Write… |
+|---|---|
+| "I've been looking at the current auth system and thinking about ways we could improve it. There are a few options to consider…" | "We need to decide between OAuth2 and SAML for the new API gateway. Here's the tradeoff." |
+
+### Conciseness
+
+| Instead of… | Write… |
+|---|---|
+| "It is worth noting that the database migration is something we should take into consideration at this point in time." | "The database migration is our next bottleneck." |
+
+### Intentional lists
+
+| Instead of… | Write… |
+|---|---|
+| "The system needs to be scalable. It also needs to be secure. And it also needs to be maintainable." | "Requirements: scalable, secure, maintainable." |
+
+### Direct over hedged
+
+| Instead of… | Write… |
+|---|---|
+| "This might potentially cause some issues that we could look at." | "This approach causes two problems: increased latency and a single point of failure." |
+
+## Cross-skill references
+
+| When you need… | Use this skill |
+|---|---|
+| A document template with section structure | `write-a-ticket`, `write-a-prd`, `write-a-skill` |
+| Guidance on what and whether to document | `style-documentation` |
+| Coding style and conventions | `style-code` |
+| Test writing style | `style-tests` |
+
+## Verification checklist
+
+- [ ] Document opens with the key takeaway (decision, conclusion, recommendation, or summary)
+- [ ] Triangular structure: broad context → narrow detail
+- [ ] No hedging, filler, preamble, or restated document title
+- [ ] Every sentence earns its place — nothing can be cut without loss
+- [ ] Lists are parallel and genuinely enumerable
+- [ ] Links point to specific locations, not top-level roots
+- [ ] Examples are under 15 lines and show only what's needed
+- [ ] References section used only for multiple links; single links are inlined