argos-harness 0.1.0

package/assets/skills/astro/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: astro
+description: Trigger: Astro site, landing page, marketing site, static site, app web. Astro 5 patterns: zero-JS defaults, islands, content collections, Tailwind 4 via Vite.
+---
+
+# Astro 5
+
+## Activation Contract
+
+Activate when building or editing an Astro site — landing pages, marketing sites, docs, or any static-first web.
+
+## Hard Rules
+
+- Static output by default. Add an adapter/SSR only when a route genuinely needs per-request rendering.
+- Zero client JS by default: build with `.astro` components. Hydrate only real interactivity, with the narrowest `client:*` directive that works.
+- Repeating content (features, FAQs, testimonials, posts) lives in content collections (`src/content.config.ts`, `defineCollection` + zod schema, `glob`/`file` loaders) — never hardcoded arrays inside pages.
+- Tailwind 4 via the `@tailwindcss/vite` plugin. Do NOT use the deprecated `@astrojs/tailwind` integration.
+- Local images through `astro:assets` `<Image>`, not raw `<img>`.
+- Every page renders `<title>` and meta description through a shared layout; install `@astrojs/sitemap`.
+
+## Decision Gates
+
+| Situation | Action |
+|-----------|--------|
+| Component needs interactivity | Try CSS/native HTML first; else a framework island with `client:visible` (or `client:idle`); `client:load` only for above-the-fold critical UI |
+| Content will repeat or grow | Content collection with zod schema |
+| One route needs fresh per-request data | Server island (`server:defer`) before converting the site to SSR |
+| Dynamic routes from content | `getStaticPaths()` + `getCollection()` |
+
+## Execution Steps
+
+1. Scaffold: `npm create astro@latest` (template: minimal), add Tailwind 4 via `@tailwindcss/vite`.
+2. Create `src/layouts/Base.astro` with head, meta, fonts, and design tokens.
+3. Build pages under `src/pages/`; extract repeating content to collections.
+4. Verify: `astro build` passes and `astro preview` renders correctly; confirm no unintended client JS shipped.
+
+## Output Contract
+
+A site that builds statically (`astro build` clean), ships zero JS unless justified, and lists every island added with its directive and reason.

package/assets/skills/axios/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: axios
+description: Patrones de Axios en TS — instancia central, interceptores, tipado de respuestas, manejo de errores y cancelación. Trigger: al tocar llamadas HTTP a APIs.
+---
+
+# Axios — convenciones
+
+## Cuándo usar este skill
+
+Al hacer una llamada HTTP a una API: crear un endpoint del cliente, agregar auth, mapear errores, o cancelar una request. Axios se cablea **una vez** en una instancia central con interceptores — los componentes/servicios importan esa instancia, no `axios` crudo con la URL a mano en cada llamada.
+
+## El patrón
+
+Una instancia por API (baseURL + interceptores), funciones tipadas encima; nunca `axios.get(fullUrl)` disperso:
+
+```ts
+export const api = axios.create({
+  baseURL: import.meta.env.VITE_APP_NEXUS_URL,
+  timeout: 15_000,
+});
+
+api.interceptors.request.use((config) => {
+  const token = getToken();
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+api.interceptors.response.use(
+  (res) => res,
+  (error) => Promise.reject(normalizeError(error)),  // un solo shape de error
+);
+
+// Servicio tipado: el genérico es el TIPO DE DATA, no el del envelope.
+export const getSession = (id: string) =>
+  api.get<Session>(`/sessions/${id}`).then((r) => r.data);
+```
+
+## Gotchas que muerden
+
+- **`api.get<T>()` tipa `response.data`, no la respuesta entera.** El `T` describe el `data`; Axios envuelve en `{ data, status, headers }`. Devuelve `r.data` desde el servicio para que el caller vea `Session`, no `AxiosResponse<Session>`.
+- **Una instancia con `baseURL`, no la URL completa por llamada.** Centraliza host/timeout/headers. Repetir `axios.get('https://…/sessions')` esparce la config y rompe al cambiar de entorno.
+- **Auth/refresh/logging en interceptores, no copiados en cada request.** El token va en un `request.use`; el 401→refresh y el mapeo de error van en `response.use`. Nada de `headers: { Authorization }` a mano en cada endpoint.
+- **`axios.isAxiosError(err)` antes de leer `err.response`.** En el `catch`, `err` es `unknown`. Sin el type guard, `err.response.data` explota en errores de red (donde `response` es `undefined` y solo hay `err.request`).
+- **Un error de red NO es un error HTTP.** Timeout/DNS/offline no traen `response`. Distingue `err.response` (el server respondió con 4xx/5xx) de `err.request` (nunca llegó) para dar el mensaje correcto.
+- **Cancela requests en vuelo con `AbortController`.** En efectos/búsqueda-as-you-type pasa `{ signal: controller.signal }` y aborta en el cleanup; sin esto, una respuesta vieja pisa a una nueva (race).
+- **4xx/5xx ya rechazan la promesa.** No revises `res.status` en el `.then`; el flujo de error vive en `catch`/el interceptor. Solo `validateStatus` cambia esa regla, y rara vez la necesitas.
+
+## Reglas duras
+
+1. Todo HTTP pasa por la instancia central con `baseURL` + interceptores; nada de `axios` crudo con URL completa suelta.
+2. Auth, refresh y normalización de error en interceptores, una sola vez.
+3. Servicios tipados con `api.get<Data>(...)` que devuelven `.data`; el genérico es la data, no el envelope.
+4. En `catch`, `axios.isAxiosError` antes de tocar `.response`; distingue error de red de error HTTP.
+5. Requests cancelables (`AbortController`) donde puede haber carreras.
+
+## Antes de declarar listo
+
+- La llamada usa la instancia central; sin URLs absolutas ni headers de auth repetidos.
+- Respuestas tipadas devolviendo `.data`; el error se maneja con `isAxiosError` y un shape único.
+- Requests que compiten se cancelan en el cleanup.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/branch-pr/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: branch-pr
+description: Create pull requests with issue-first checks. Trigger: creating, opening, or preparing PRs for review.
+---
+
+## When to Use
+
+Use this skill when:
+- Creating a pull request for any change
+- Preparing a branch for submission
+- Helping a contributor open a PR
+
+---
+
+## Critical Rules
+
+1. **Every PR MUST link an approved issue** — no exceptions
+2. **Every PR MUST have exactly one `type:*` label**
+3. **Automated checks must pass** before merge is possible
+4. **Blank PRs without issue linkage will be blocked** by GitHub Actions
+
+---
+
+## Workflow
+
+```
+1. Verify issue has `status:approved` label
+2. Create branch: type/description (see Branch Naming below)
+3. Implement changes with conventional commits
+4. Run shellcheck on modified scripts
+5. Open PR using the template
+6. Add exactly one type:* label
+7. Wait for automated checks to pass
+```
+
+---
+
+## Branch Naming
+
+Branch names MUST match this regex:
+
+```
+^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
+```
+
+**Format:** `type/description` — lowercase, no spaces, only `a-z0-9._-` in description.
+
+| Type | Branch pattern | Example |
+|------|---------------|---------|
+| Feature | `feat/<description>` | `feat/user-login` |
+| Bug fix | `fix/<description>` | `fix/zsh-glob-error` |
+| Chore | `chore/<description>` | `chore/update-ci-actions` |
+| Docs | `docs/<description>` | `docs/installation-guide` |
+| Style | `style/<description>` | `style/format-scripts` |
+| Refactor | `refactor/<description>` | `refactor/extract-shared-logic` |
+| Performance | `perf/<description>` | `perf/reduce-startup-time` |
+| Test | `test/<description>` | `test/add-setup-coverage` |
+| Build | `build/<description>` | `build/update-shellcheck` |
+| CI | `ci/<description>` | `ci/add-branch-validation` |
+| Revert | `revert/<description>` | `revert/broken-setup-change` |
+
+---
+
+## PR Body Format
+
+The PR template is at `.github/PULL_REQUEST_TEMPLATE.md`. Every PR body MUST contain:
+
+### 1. Linked Issue (REQUIRED)
+
+```markdown
+Closes #<issue-number>
+```
+
+Valid keywords: `Closes #N`, `Fixes #N`, `Resolves #N` (case insensitive).
+The linked issue MUST have the `status:approved` label.
+
+### 2. PR Type (REQUIRED)
+
+Check exactly ONE in the template and add the matching label:
+
+| Checkbox | Label to add |
+|----------|-------------|
+| Bug fix | `type:bug` |
+| New feature | `type:feature` |
+| Documentation only | `type:docs` |
+| Code refactoring | `type:refactor` |
+| Maintenance/tooling | `type:chore` |
+| Breaking change | `type:breaking-change` |
+
+### 3. Summary
+
+1-3 bullet points of what the PR does.
+
+### 4. Changes Table
+
+```markdown
+| File | Change |
+|------|--------|
+| `path/to/file` | What changed |
+```
+
+### 5. Test Plan
+
+```markdown
+- [x] Scripts run without errors: `shellcheck scripts/*.sh`
+- [x] Manually tested the affected functionality
+- [x] Skills load correctly in target agent
+```
+
+### 6. Contributor Checklist
+
+All boxes must be checked:
+- Linked an approved issue
+- Added exactly one `type:*` label
+- Ran shellcheck on modified scripts
+- Skills tested in at least one agent
+- Docs updated if behavior changed
+- Conventional commit format
+- No `Co-Authored-By` trailers
+
+---
+
+## Automated Checks (all must pass)
+
+| Check | Job name | What it verifies |
+|-------|----------|-----------------|
+| PR Validation | `Check Issue Reference` | Body contains `Closes/Fixes/Resolves #N` |
+| PR Validation | `Check Issue Has status:approved` | Linked issue has `status:approved` |
+| PR Validation | `Check PR Has type:* Label` | PR has exactly one `type:*` label |
+| CI | `Shellcheck` | Shell scripts pass `shellcheck` |
+
+---
+
+## Conventional Commits
+
+Commit messages MUST match this regex:
+
+```
+^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
+```
+
+**Format:** `type(scope): description` or `type: description`
+
+- `type` — required, one of: `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`
+- `(scope)` — optional, lowercase with `a-z0-9._-`
+- `!` — optional, indicates breaking change
+- `description` — required, starts after `: `
+
+Type-to-label mapping:
+
+| Commit type | PR label |
+|-------------|----------|
+| `feat` | `type:feature` |
+| `fix` | `type:bug` |
+| `docs` | `type:docs` |
+| `refactor` | `type:refactor` |
+| `chore` | `type:chore` |
+| `style` | `type:chore` |
+| `perf` | `type:feature` |
+| `test` | `type:chore` |
+| `build` | `type:chore` |
+| `ci` | `type:chore` |
+| `revert` | `type:bug` |
+| `feat!` / `fix!` | `type:breaking-change` |
+
+Examples:
+```
+feat(scripts): add Codex support to setup.sh
+fix(skills): correct topic key format in sdd-apply
+docs(readme): update multi-model configuration guide
+refactor(skills): extract shared persistence logic
+chore(ci): add shellcheck to PR validation workflow
+perf(scripts): reduce setup.sh execution time
+style(skills): fix markdown formatting
+test(scripts): add setup.sh integration tests
+ci(workflows): add branch name validation
+revert: undo broken setup change
+feat!: redesign skill loading system
+```
+
+---
+
+## Commands
+
+```bash
+# Create branch
+git checkout -b feat/my-feature main
+
+# Run shellcheck before pushing
+shellcheck scripts/*.sh
+
+# Push and create PR
+git push -u origin feat/my-feature
+gh pr create --title "feat(scope): description" --body "Closes #N"
+
+# Add type label to PR
+gh pr edit <pr-number> --add-label "type:feature"
+```
+
+_Adapted from a skill originally authored by gentleman-programming._

package/assets/skills/bullmq/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: bullmq
+description: Jobs y colas con BullMQ sobre Redis — Queue/Worker/QueueEvents, jobs idempotentes, retries con backoff, concurrency y graceful shutdown. Trigger: al crear/tocar un job, un worker o al encolar trabajo async.
+---
+
+# BullMQ — jobs & queues
+
+BullMQ mueve trabajo pesado o diferido fuera del request: un **productor** encola (`Queue.add`) y un **worker** (proceso aparte) lo procesa. La conexión es Redis (`ioredis`). El productor y el worker viven en procesos distintos y comparten solo el nombre de la cola.
+
+## Cuándo usar este skill
+
+Al crear una cola o un job nuevo, tocar el worker, encolar trabajo desde un handler/hook, o depurar jobs que se cuelgan, se reintentan en loop o se pierden.
+
+## El patrón
+
+```ts
+// Productor (en un request/hook): encola y responde rápido, NO esperes el resultado.
+await queue.add("send-welcome", { userId }, {
+  attempts: 3,
+  backoff: { type: "exponential", delay: 1000 },
+  removeOnComplete: 1000,   // no dejes que Redis crezca sin límite
+  removeOnFail: 5000,
+});
+
+// Worker (proceso aparte): una responsabilidad por worker/cola.
+const worker = new Worker("emails", async (job) => {
+  // idempotente: correr dos veces el mismo job no debe duplicar efectos
+  return sendEmail(job.data);
+}, { connection, concurrency: 5 });
+```
+
+## Reglas duras
+
+1. **Jobs idempotentes.** Un job puede reintentarse o entregarse dos veces. Usa un id determinista (`jobId`) o un guard de "ya procesado" para efectos no repetibles (cobros, emails, mutaciones críticas).
+2. **`attempts` + `backoff` siempre.** Un job sin reintentos muere al primer error transitorio; uno sin backoff martillea el recurso que falla. Exponencial por default.
+3. **El productor NO espera el resultado.** Encola y responde; el valor del job se consume por eventos (`QueueEvents`) o releyendo estado, no bloqueando el request.
+4. **`removeOnComplete`/`removeOnFail`.** Sin límites, Redis se llena de jobs viejos. Acota siempre.
+5. **Graceful shutdown.** En `SIGTERM`/`SIGINT`, `await worker.close()` antes de salir para no matar un job a medias. Un worker que no cierra limpio deja jobs en `active` colgados.
+6. **Errores que deben reintentar → lanza; errores permanentes → no.** Un input inválido no se arregla reintentando: valida antes de encolar o marca el job como fallido sin reintento (`attempts: 1` o un error no-recuperable).
+7. **Una responsabilidad por worker.** No metas varios tipos de trabajo no relacionado en un solo `Worker` con `if job.name`; sepáralos por cola.
+
+## Gotchas que muerden
+
+- **La `connection` de ioredis para BullMQ necesita `maxRetriesPerRequest: null`** — si no, BullMQ lanza al reconectar.
+- **`concurrency` alto no es gratis**: cada job concurrente abre conexiones/CPU. Súbelo con medida, no por default.
+- **Un job "perdido"** casi siempre es: el worker no está corriendo, apunta a otra cola/Redis, o crasheó sin `removeOnFail` y quedó en `failed`. Revisa el estado del job antes de asumir un bug de lógica.
+- **Delayed/repeatable jobs** viven en Redis: cambiar el patrón de un repeatable no borra el viejo — límpialo explícitamente.
+
+## Antes de declarar listo
+
+- El job es idempotente (o tiene guard de duplicados) y define `attempts` + `backoff`.
+- El worker cierra en `SIGTERM`/`SIGINT` (`worker.close()`).
+- `removeOnComplete`/`removeOnFail` acotados; la `connection` usa `maxRetriesPerRequest: null`.
+- El productor no bloquea el request esperando el job.
+- El quality gate del repo (`qualityGate.fast` en `argos.config.json`) en verde.

package/assets/skills/chained-pr/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: chained-pr
+description: Split oversized changes into chained PRs that protect review focus. Trigger: PRs over 400 lines, stacked PRs, review slices.
+---
+
+## Activation Contract
+
+Load this skill when a planned PR may exceed **400 changed lines**, SDD forecasts `400-line budget risk: High` or `Chained PRs recommended: Yes`, or the user asks for chained/stacked PRs, review slices, or reviewer-load control.
+
+## Hard Rules
+
+- Split PRs over **400 changed lines** unless a maintainer explicitly accepts `size:exception`.
+- Keep each PR reviewable in about **≤60 minutes**.
+- Use one deliverable work unit per PR; keep tests/docs with the unit they verify.
+- State start, end, prior dependencies, follow-up work, and out-of-scope items in every chained PR.
+- Every child PR must include a dependency diagram marking the current PR with `📍`.
+- In Feature Branch Chain, create a draft/no-merge tracker PR; child PR #1 targets the tracker branch, later children target the immediate parent branch.
+- Treat polluted diffs as base bugs: retarget or rebase until only the current work unit appears.
+- Do not mix chain strategies after the user chooses one.
+
+## Decision Gates
+
+| Condition | Action |
+|---|---|
+| PR ≤400 changed lines and focused | Keep single PR. |
+| PR >400, each slice can land independently | Use Stacked PRs to main. |
+| PR >400, feature must integrate before main | Use Feature Branch Chain with tracker. |
+| Generated/vendor/migration diff cannot split cleanly | Ask maintainer for `size:exception`. |
+| SDD provides `delivery_strategy` | Follow it before apply/PR creation. |
+
+## Execution Steps
+
+1. Estimate changed lines and identify independent work units.
+2. Ask for a chain strategy when none is cached and the budget is exceeded.
+3. Create branches/PRs using the chosen strategy only.
+4. Add Chain Context to each PR without replacing the repo PR template.
+5. Verify each PR independently: CI/tests/docs/manual checks, rollback scope, and clean diff.
+6. Keep tracker PR draft/no-merge until all child PRs are reviewed and integrated.
+
+## Output Contract
+
+Return the chosen strategy, PR order, current PR boundary, dependency diagram, review budget (`additions + deletions`), verification plan, and any `size:exception` rationale.
+
+## References
+
+- [references/chaining-details.md](references/chaining-details.md) — strategy diagrams, PR body section, branch commands, and reviewer guidance.
+
+_Adapted from a skill originally authored by gentleman-programming._

package/assets/skills/chained-pr/references/chaining-details.md

@@ -0,0 +1,99 @@
+# Chained PR Details
+
+## Strategy Notes
+
+| | Stacked PRs to main | Feature Branch Chain |
+|---|---|---|
+| Speed | Each slice can ship in order | Full feature waits for tracker merge |
+| Rollback | Revert individual main PRs | Revert/hold the whole feature branch |
+| Risk | Partial behavior may land | Nothing lands until the chain completes |
+| Complexity | Simpler retarget/rebase flow | Requires tracker and strict diff hygiene |
+
+## Feature Branch Chain
+
+Use when the feature branch accumulates the final integration while child PRs are reviewed as focused slices.
+
+```text
+main
+ └── feat/my-feature              ← tracker/final integration branch
+      ↑ PR #1 base: feat/my-feature
+      └── feat/my-feature-01-core
+           ↑ PR #2 base: feat/my-feature-01-core
+           └── feat/my-feature-02-shared
+                ↑ PR #3 base: feat/my-feature-02-shared
+                └── feat/my-feature-03-slice
+```
+
+Steps:
+
+1. Create the feature/tracker branch from `main`.
+2. Open the tracker PR to `main`; mark it draft/no-merge.
+3. Create PR #1 from a child branch and target it to the tracker branch.
+4. Create each later child branch from the previous PR branch and target it to that parent branch.
+5. Merge/integrate children in order; merge the tracker only after the chain is complete.
+
+## Stacked PRs to Main
+
+Use when each slice can land on `main` in order.
+
+```text
+main <- PR 1: foundation
+          └── PR 2: feature slice built on PR 1
+                └── PR 3: docs/tests built on PR 2
+```
+
+After a parent PR merges, rebase/retarget the next PR so GitHub shows only the current slice.
+
+## Chain Context Section
+
+Append this section to the repo PR template; do not replace required issue/checklist sections.
+
+```markdown
+## Chain Context
+
+| Field | Value |
+|-------|-------|
+| Chain | <feature or stack name> |
+| Tracker PR | <#NNN or "Not needed"> |
+| Position | <N of total> |
+| Base | `<target branch>` |
+| Depends on | <PR/issue/link or "None"> |
+| Follow-up | <next PR or "None"> |
+| Review budget | <changed lines> / 400 |
+| Starts at | <branch, PR, or state this builds on> |
+| Ends with | <standalone result delivered by this PR> |
+
+### Chain Overview
+
+```text
+main
+ └── #NNN Previous PR
+      └── 📍 #NNN This PR
+           └── #NNN Next PR
+```
+
+### Scope
+- Includes: <focused unit>
+- Excludes: <deferred work>
+
+### Autonomy
+- [ ] CI is expected to pass for this PR branch
+- [ ] This PR has one deliverable scope
+- [ ] This PR can be rolled back without unrelated changes
+- [ ] Tests, docs, or manual verification cover this unit
+```
+
+## Commands
+
+```bash
+gh pr view <PR_NUMBER> --json additions,deletions,changedFiles,title,url
+gh pr create --base feat/my-feature --title "feat(scope): focused slice" --body-file pr-body.md
+gh pr create --base feat/my-feature-01-core --title "feat(scope): next focused slice" --body-file pr-body.md
+```
+
+## Reviewer Guidance
+
+- Ask for a split when a PR exceeds 400 changed lines without `size:exception`.
+- Recommend Feature Branch Chain when work must integrate before `main`.
+- Recommend stacked PRs when each slice can merge independently.
+- Review child PRs against immediate parent branches; a polluted diff is a branching bug.

package/assets/skills/cognitive-doc-design/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: cognitive-doc-design
+description: Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.
+---
+
+## When to Use
+
+Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
+
+Use it especially for:
+
+- PR descriptions and review notes.
+- Contributor or maintainer guides.
+- Architecture, workflow, or onboarding docs.
+- Any doc that currently feels long, dense, or hard to scan.
+
+## Critical Patterns
+
+| Pattern | Rule |
+|---------|------|
+| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
+| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
+| Chunking | Group related information into small sections. Keep flat lists short. |
+| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
+| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
+| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
+
+## Documentation Shape
+
+Use this default structure unless the repo already provides a stronger template:
+
+```markdown
+# <Outcome-oriented title>
+
+<One paragraph: what changed, who it helps, and why it matters.>
+
+## Quick path
+
+1. <First action>
+2. <Second action>
+3. <Verification or expected result>
+
+## Details
+
+| Topic | Decision |
+|-------|----------|
+| <area> | <concise explanation> |
+
+## Checklist
+
+- [ ] <Reader can confirm this>
+- [ ] <Reader can confirm that>
+
+## Next step
+
+<Link or action that continues the workflow.>
+```
+
+## PR and Review Docs
+
+When documenting a PR, reduce reviewer burnout by making the review path explicit:
+
+- State what to review first.
+- State what is intentionally out of scope.
+- Link the previous and next PR when work is chained.
+- Keep each section focused on one decision or unit of work.
+- Use checklists for acceptance criteria and verification.
+
+## Commands
+
+```bash
+# Check markdown files changed in the current branch
+git diff --name-only -- '*.md'
+
+# Inspect PR changed-line count for cognitive load
+gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
+```
+
+---
+
+_Adapted from a skill originally authored by gentleman-programming._

package/assets/skills/comment-writer/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: comment-writer
+description: Write warm, direct collaboration comments. Trigger: PR feedback, issue replies, reviews, Slack messages, or GitHub comments.
+---
+
+## When to Use
+
+Load this skill whenever you write a comment that another human will read.
+
+Use it for:
+
+- GitHub PR or issue comments.
+- Review feedback and requested changes.
+- Maintainer replies.
+- Slack, Discord, or async project updates.
+
+## Voice Rules
+
+| Rule | Requirement |
+|------|-------------|
+| Be useful fast | Start with the actionable point. Do not recap the whole PR before feedback. |
+| Be warm and direct | Sound like a thoughtful teammate, not a corporate bot. |
+| Keep it short | Prefer 1 to 3 short paragraphs or a tight bullet list. |
+| Explain why | Give the technical reason when asking for a change. |
+| Avoid pile-ons | Comment on the highest-value issue, not every tiny preference. |
+| Match target context language | Write in the target context language by default: Spanish issue/thread -> Spanish comment, English issue/thread -> English comment, mixed context -> target message language. If the user explicitly requests a language or tone, follow that request. For Spanish comments, use neutral/professional Spanish by default unless the user or target context clearly calls for regional tone. |
+| No em dashes | Use commas, periods, or parentheses instead. |
+
+## Comment Formula
+
+```text
+<Direct observation or request>
+
+<Why it matters, only if needed>
+
+<Concrete next action>
+```
+
+## Examples
+
+### Request change
+
+```markdown
+Good approach overall. I'd split this into a separate commit because it mixes validation logic with UI wiring.
+
+That keeps the reviewer's focus narrower and makes rollback cleaner if the integration fails.
+```
+
+### Approve with a note
+
+```markdown
+Approved. The scope is clear and the change is well-contained.
+
+For the next PR, add links to the previous and following PRs so the chain stays navigable.
+```
+
+### Ask for split
+
+```markdown
+This PR exceeds the 400-line budget, so we need to split it or justify `size:exception`.
+
+Suggested order: foundation + tests first, then integration, then docs. That gives each review a clear start and end.
+```
+
+## Commands
+
+```bash
+# Inspect a PR before writing review feedback
+gh pr view <PR_NUMBER> --json title,body,additions,deletions,changedFiles
+```
+
+---
+
+_Adapted from a skill originally authored by gentleman-programming._