@reddb-io/red-skills-dev 2.75.2

package/skills/misc/migrate-to-shoehorn/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: migrate-to-shoehorn
+description: Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
+---
+
+# Migrate to Shoehorn
+
+**Replace `as` assertions in test files with `fromPartial()` or `fromAny()` from `@total-typescript/shoehorn`.**
+
+## Why shoehorn?
+
+`shoehorn` lets you pass partial data in tests while keeping TypeScript happy. It replaces `as` assertions with `fromPartial()` for partial data and `fromAny()` for intentionally wrong types.
+
+**Test code only.** Never use shoehorn in production code.
+
+Problems with `as` in tests:
+
+- Trained not to use it
+- Must manually specify target type
+- Double-as (`as unknown as Type`) for intentionally wrong data
+
+## Install
+
+```bash
+npm i @total-typescript/shoehorn
+```
+
+## Migration patterns
+
+### `as Type` (and large objects with few needed properties) → `fromPartial()`
+
+Whether you wrote `as Request` or hand-faked every property of a large type, only the properties the test cares about matter. `fromPartial()` keeps those and lets TypeScript accept the rest.
+
+Before:
+
+```ts
+type Request = {
+  body: { id: string };
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+  // ...20 more properties
+};
+
+it("gets user by id", () => {
+  // Faking the entire Request, or papering over it with `as`
+  getUser({ body: { id: "123" } } as Request);
+});
+```
+
+After:
+
+```ts
+import { fromPartial } from "@total-typescript/shoehorn";
+
+it("gets user by id", () => {
+  getUser(fromPartial({ body: { id: "123" } }));
+});
+```
+
+### `as unknown as Type` → `fromAny()`
+
+Before:
+
+```ts
+getUser({ body: { id: 123 } } as unknown as Request); // wrong type on purpose
+```
+
+After:
+
+```ts
+import { fromAny } from "@total-typescript/shoehorn";
+
+getUser(fromAny({ body: { id: 123 } }));
+```
+
+## When to use each
+
+| Function        | Use case                                           |
+| --------------- | -------------------------------------------------- |
+| `fromPartial()` | Pass partial data that still type-checks           |
+| `fromAny()`     | Pass intentionally wrong data (keeps autocomplete) |
+
+## Workflow
+
+1. **Gather requirements** - ask user:
+   - What test files have `as` assertions causing problems?
+   - Are they dealing with large objects where only some properties matter?
+   - Do they need to pass intentionally wrong data for error testing?
+
+2. **Install and migrate**:
+   - [ ] Install: `npm i @total-typescript/shoehorn`
+   - [ ] Find test files with `as` assertions: `grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"`
+   - [ ] Replace `as Type` with `fromPartial()`
+   - [ ] Replace `as unknown as Type` with `fromAny()`
+   - [ ] Add imports from `@total-typescript/shoehorn`
+   - [ ] Run type check to verify

package/skills/misc/setup-pre-commit/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: setup-pre-commit
+description: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
+disable-model-invocation: true
+---
+
+# Setup Pre-Commit Hooks
+
+**Enforce lint + tests before commit.**
+
+## What This Sets Up
+
+- **Husky** pre-commit hook
+- **lint-staged** running Prettier on all staged files
+- **Prettier** config (if missing)
+- **typecheck** and **test** scripts in the pre-commit hook
+
+## Steps
+
+### 1. Detect package manager
+
+Check for `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lockb` (bun). Use whichever is present. Default to npm if unclear.
+
+### 2. Install dependencies
+
+Install as devDependencies:
+
+```
+husky lint-staged prettier
+```
+
+### 3. Initialize Husky
+
+```bash
+npx husky init
+```
+
+This creates `.husky/` dir and adds `prepare: "husky"` to package.json.
+
+### 4. Create `.husky/pre-commit`
+
+Write this file (no shebang needed for Husky v9+):
+
+```
+npx lint-staged
+npm run typecheck
+npm run test
+```
+
+**Adapt**: Replace `npm` with detected package manager. If repo has no `typecheck` or `test` script in package.json, omit those lines and tell the user.
+
+### 5. Create `.lintstagedrc`
+
+```json
+{
+  "*": "prettier --ignore-unknown --write"
+}
+```
+
+### 6. Create `.prettierrc` (if missing)
+
+Only create if no Prettier config exists. Use these defaults:
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "semi": true,
+  "arrowParens": "always"
+}
+```
+
+### 7. Verify
+
+- [ ] `.husky/pre-commit` exists and is executable
+- [ ] `.lintstagedrc` exists
+- [ ] `prepare` script in package.json is `"husky"`
+- [ ] `prettier` config exists
+- [ ] Run `npx lint-staged` to verify it works
+
+### 8. Commit
+
+Stage all changed/created files and commit with message: `Add pre-commit hooks (husky + lint-staged + prettier)`
+
+This will run through the new pre-commit hooks — a good smoke test that everything works.
+
+## Notes
+
+- Husky v9+ doesn't need shebangs in hook files
+- `prettier --ignore-unknown` skips files Prettier can't parse (images, etc.)
+- The pre-commit runs lint-staged first (fast, staged-only), then full typecheck and tests

package/skills/productivity/README.md

@@ -0,0 +1,8 @@
+# Productivity
+
+General workflow tools, not code-specific.
+
+- **[reflect](./reflect/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved.
+- **[ff](./ff/SKILL.md)** — Fast-forward clarity: pick a framing, get your message rewritten into it, then choose whether to dispatch (execute) it.
+- **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work.
+- **[write-a-skill](./write-a-skill/SKILL.md)** — Create new skills with proper structure, progressive disclosure, and bundled resources.

package/skills/productivity/ff/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ff
+description: Reframes the user's message into one chosen framing through a two-step interaction — first asks which framing to rewrite into, then generates that single rewrite and asks whether to dispatch (execute) it. Use when the user invokes `/ff`, says fast-forward, asks to rewrite their own message, or wants to clarify intent before acting.
+argument-hint: "[--dispatch|-d] [text to reframe]"
+disable-model-invocation: true
+---
+
+# /ff
+
+Fast-forward clarity. Reframe the user's latest message, or the text passed after
+`/ff`, into **one** chosen framing — through two sequential questions, asked one
+at a time with the user's interaction between them.
+
+`/ff` does NOT dump every framing at once. It asks which framing the user wants
+first, generates only that one rewrite, then asks whether to dispatch it.
+
+<what-to-do>
+
+**Reframe the user's message through exactly one chosen framing, via two sequential interactions — pick the framing first, generate the rewrite second.** Never skip ahead or produce multiple rewrites.
+
+Run these two steps in order. Ask one question, wait for the answer, then proceed to the next.
+
+### Step 1 — choose the framing (no rewrite yet — stop and wait for the user's pick)
+
+Present the framing menu with a single recommendation, then **stop and wait**. Do
+not generate any rewrite yet — the user picks by label, before seeing any output.
+
+```md
+How do you want to rewrite your content?
+
+I think you want (x), because ...
+
+(a) For a junior dev
+(b) For a 10-year-old
+(c) For a senior dev
+(d) As an improved prompt
+(e) As an implementable issue
+(f) As a decision request
+(g) Short and direct
+```
+
+The user picks with phrases like `d`, `use a`, or `go with that one`.
+
+### Step 2 — generate the chosen rewrite, then ask to dispatch (only after the user picks from Step 1)
+
+Produce **only** the chosen framing's rewrite and present it, then ask whether to
+dispatch:
+
+```md
+Result:
+{result}
+
+Would you like to dispatch it? Yes/no
+```
+
+- **Yes** → adopt `{result}` as the active message and **carry out the underlying
+  task** immediately.
+- **No** → hand `{result}` back and **stop**. Do not execute anything.
+
+**`--dispatch`/`-d` shortcut**: if the flag was passed in the invocation, **skip
+the Yes/no question** — present the `Result:` and immediately dispatch (auto-yes).
+The flag may appear anywhere in the arguments; strip it before reframing the
+remaining text.
+
+### Hard rules
+
+- ✅ Generate exactly **one** rewrite — the chosen framing. Never preview all of them.
+- ✅ In Step 1, reframe only: do not solve the task, edit files, run commands, or
+  continue a paused `/start`, `/diagnose`, `/afk`, or implementation task.
+- ✅ Keep the rewrite tight: a few lines, or a compact summary when the source is long.
+- ❌ Do not execute anything until the user answers Yes in Step 2 (or passed `-d`).
+- ❌ Do not collapse the two steps into one turn — the menu and the result are
+  separate questions.
+
+</what-to-do>
+
+<supporting-info>
+
+## Worked example — framing (e) end-to-end
+
+User invokes `/ff implement error handling for this API`.
+
+**Step 1 output (stop — wait for the user's pick):** print the Step 1 framing
+menu (see `<what-to-do>`), recommending `(e)` — "because it's an implementation
+task that could be scoped as a ticket."
+
+User replies: `e`
+
+**Step 2 output (generate + ask to dispatch):**
+
+```
+Result:
+**Add error handling to the payment API endpoint**
+Context: The `/api/payment` endpoint currently lets uncaught exceptions propagate to the caller.
+Scope: Wrap the handler in try/catch; return `{ error: "…", code: 500 }` on failure; log via the existing logger.
+Acceptance criteria: non-2xx responses are structured JSON; errors are logged; no uncaught exceptions escape.
+Validation: manual smoke test + existing integration tests pass.
+
+Would you like to dispatch it? Yes/no
+```
+
+User replies: `yes` → carry out the implementation task described above.
+
+---
+
+## Framing semantics
+
+- **(a) For a junior dev**: precise but simple technical language, minimal jargon, practical examples.
+- **(b) For a 10-year-old**: plain language, one analogy if useful, no patronizing tone.
+- **(c) For a senior dev**: dense technical vocabulary, explicit assumptions, constraints, edge cases, and tradeoffs.
+- **(d) As an improved prompt**: prompt-engineered request with role/context, objective, constraints, desired output, and success criteria.
+- **(e) As an implementable issue**: title, context, scope, acceptance criteria, and validation.
+- **(f) As a decision request**: decision needed, options, tradeoffs, recommendation, and what answer unblocks.
+- **(g) Short and direct**: the shortest clear version.
+
+</supporting-info>

package/skills/productivity/handoff/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+**Hand over context, not content — reference existing artifacts; do not reproduce them.** The next agent needs enough to continue, not a transcript.
+
+Write a handoff document to a path from `mktemp -t handoff-XXXXXX.md` (read the file before writing). Cover:
+
+- **State:** what was done, what is in progress, what is blocked
+- **Next action:** the first concrete step the next session should take
+- **Skills:** which skills the next session should invoke, if any
+- **Refs:** paths or URLs to any Specs, plans, ADRs, issues, commits, or diffs — do not reproduce their content
+
+Use this template:
+
+```markdown
+# Handoff — <date>
+
+## State
+<what was done / in progress / blocked>
+
+## Next action
+<the first concrete step>
+
+## Skills to invoke
+<list of /skill names, if any>
+
+## References
+- <path-or-url>: <one-line description>
+```
+
+Redact API keys, passwords, tokens, and personally identifiable information before writing.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/skills/productivity/reflect/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: reflect
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, reflect on a design, or mentions "reflect".
+---
+
+<what-to-do>
+
+**Interview the user — one question per turn, one recommendation per question — until every branch of this plan is understood.** Do not stack questions; do not skip ahead.
+
+Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, include your recommended answer with a one-sentence reason.
+
+Ask the questions one at a time. Wait for the user's reply before proceeding.
+
+If a question can be answered by exploring the codebase, explore the codebase instead of asking.
+
+When the reflection session ends, run the shared end-of-session doc-landing finalizer in [`/start`'s DOC-LANDING-FINALIZER.md](../../engineering/start/DOC-LANDING-FINALIZER.md) before exiting.
+
+</what-to-do>

package/skills/productivity/write-a-skill/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: write-a-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Writing Skills
+
+<what-to-do>
+
+## Process
+
+1. **Gather requirements** — ask the user, before drafting anything:
+   - What task or domain does the skill cover?
+   - Which specific use cases must it handle?
+   - Does it need executable scripts, or just instructions?
+   - Any reference material to bundle?
+
+2. **Draft the skill** — produce:
+   - A SKILL.md with concise, imperative instructions.
+   - Extra reference files only when content would push SKILL.md past ~100 lines.
+   - Utility scripts only when a deterministic operation repeats.
+
+3. **Review with the user** — present the draft and ask whether it covers the
+   use cases, what is missing or unclear, and which section needs more or less
+   detail. Do not ship before this loop closes.
+
+</what-to-do>
+
+<supporting-info>
+
+## Skill structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── REFERENCE.md       # Detailed docs (only if needed)
+├── EXAMPLES.md        # Usage examples (only if needed)
+└── scripts/           # Utility scripts (only if needed)
+    └── helper.js
+```
+
+## SKILL.md template
+
+```md
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+---
+
+# Skill Name
+
+<what-to-do>
+
+[The primary directive — imperative, non-negotiable steps the agent
+executes literally. DOs / DON'Ts here are hard constraints.]
+
+</what-to-do>
+
+<supporting-info>
+
+[Reference material consulted on demand — formats, file layouts, trigger
+conditions, examples. Link one level deep: see [REFERENCE.md](REFERENCE.md).]
+
+</supporting-info>
+```
+
+## Description requirements
+
+The description is **the only thing the agent sees before loading the skill** —
+write it for the picker, not the reader. It is surfaced in the system prompt
+beside every other installed skill, and the agent chooses from those lines
+alone.
+
+Give the agent just enough to know two things: what the capability is, and
+when to trigger it (keywords, contexts, file types).
+
+**Format**:
+
+- Max 1024 chars.
+- Third person.
+- First sentence: what it does.
+- Second sentence: starts with the literal `"Use when"` so the trigger is
+  matchable verbatim.
+
+**Good** — distinguishes itself from every other document skill:
+
+```
+Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
+```
+
+**Bad** — gives the agent no way to pick it:
+
+```
+Helps with documents.
+```
+
+## Trigger decision (user-invoked vs model-invoked)
+
+Decide **before writing the description**: should the model reach for this skill
+on its own, or only the operator by typing `/skill-name`? Set
+`disable-model-invocation: true` in the frontmatter to make a skill **user-only**
+— the model can no longer trigger it; it runs solely on the explicit command.
+
+The trade-off is where the load lands. A **model-invocable** skill's description
+is loaded into every session's context — a standing **context load on the agent**,
+paid on every turn whether or not the skill fires. A **user-only** skill imposes
+**cognitive load on the operator** instead — they must remember the command
+exists — but costs the agent zero standing context.
+
+**Default rule: deliberate operational commands ship user-only.** Setup wizards,
+reports, and dispatch/maintenance verbs are things the operator decides to run —
+`disable-model-invocation: true`. Skills the model should proactively reach for
+stay model-invocable, and then **the description must earn its context cost** —
+every session pays for it, so it has to distinguish itself from every other line.
+
+User-only also removes a **class of problem**: model invocation is unpredictable.
+Even a well-scoped description may not fire when it fits — the model can skip a
+context pointer it should have followed. A `/command` the operator types can't be
+missed that way, so deliberate commands become reliable by construction.
+
+## When to add scripts
+
+Add a utility script when the operation is deterministic (validation,
+formatting), when the same code would be generated repeatedly, or when errors
+need explicit handling. Scripts save tokens and beat generated code on
+reliability.
+
+## When to split files
+
+Split into a separate file when SKILL.md exceeds ~100 lines, when content spans
+distinct domains (finance vs sales schemas), or when advanced features are
+rarely needed — keep references one level deep so the agent never chases a chain.
+
+**Branch-gated external references** — reference material consumed by only one
+branch (mode / flag / subcommand) of the skill moves to a sibling file behind a
+one-line context pointer: `if X, read Y`. The unused branch then costs the agent
+nothing until it fires. In-repo exemplars: `afk`'s Actions-lane reference
+(`actions-lane.md`, read only on the GitHub-Actions branch), `tdd`'s bundled
+reference files (`mocking.md`, `refactoring.md`, …, each pulled in only when that
+sub-topic comes up), and `prototype`'s two branch files (`LOGIC.md` vs `UI.md`,
+one per route the skill takes).
+
+## Leg-work splitting (hide the goal to protect the gather phase)
+
+When an early gather/interview phase keeps getting **rushed because the final
+artifact goal is visible in the same skill**, split the phase into its own skill
+so the future step is hidden. With the payoff out of sight, the agent can't skip
+ahead to it — the gather phase runs to completion on its own terms.
+
+In-repo exemplars: `/start` (grill and sharpen the plan) hands off to `/to-spec`
+(publish the Spec) instead of doing both, so the grilling isn't cut short by the
+pull toward shipping; and `writing-fragments` is separate from `writing-shape` /
+`writing-beats` so the raw-material gather isn't rushed toward the finished piece.
+
+## TROUBLESHOOTING references
+
+Operational TROUBLESHOOTING references use one fixed playbook entry format:
+Symptom -> Confirm -> Recover -> Root fix. Define that convention here, and have
+each reference link back to `write-a-skill` instead of re-explaining the format.
+
+Docs-contract tests for TROUBLESHOOTING references assert file existence, the SKILL.md link, and stable load-bearing headings. They do not assert prose wording;
+pinning prose turns a documentation contract into a stale-doc test.
+
+## SKILL.md writing style
+
+Section structure (`<what-to-do>` / `<supporting-info>`) decides *where* a
+sentence goes. Sentence-level style and Steering failure modes live in
+[WRITING-STYLE.md](WRITING-STYLE.md); read it before drafting or reviewing any
+RedSkills SKILL.md.
+
+## Review checklist (run after the draft compiles)
+
+- [ ] Description ends with the literal `"Use when …"` trigger.
+- [ ] SKILL.md stays under ~100 lines (excluding this meta-skill).
+- [ ] No time-sensitive info.
+- [ ] One term per concept — no synonym drift.
+- [ ] Concrete before → after or input → output examples included.
+- [ ] References stay one level deep.
+- [ ] Steps read imperative and bold-led — the skill follows its own style.
+- [ ] **Deletion test** — for each paragraph, ask "would the agent behave
+  differently if this were deleted?" Delete the no-ops.
+- [ ] **Trigger decision recorded** — the skill is explicitly user-only
+  (`disable-model-invocation: true`) or model-invocable with a description that
+  earns its context cost.
+- [ ] **Negation check** — each prohibition has a paired positive alternative on
+  the same line; rewrite standalone "don't X" entries as "do Y instead".
+- [ ] **Negative-space audit** — each silence is a deliberate open branch, not an
+  oversight; fill gaps or name them explicitly.
+
+</supporting-info>

package/skills/productivity/write-a-skill/WRITING-STYLE.md

@@ -0,0 +1,62 @@
+# SKILL.md Writing Style
+
+Section structure (`<what-to-do>` / `<supporting-info>`) decides *where* a
+sentence goes; this section decides *how the sentence reads*. Apply these nine
+sentence-level techniques — borrowed from `anthropics/launch-your-agent` — when
+writing any RedSkills SKILL.md. Each carries a one-line before → after.
+
+1. **Bold lead-in + gloss** — open a step with the imperative in bold, then
+   explain it.
+   - Before: `You should gather the requirements from the user first.`
+   - After: `**Gather requirements** — ask the user what task the skill covers.`
+
+2. **Maxim/slogan compression** — fold a rule into one memorable line.
+   - Before: `The description matters because it is what the agent uses to decide whether to load the skill.`
+   - After: `The description is the only thing the agent sees before loading — write it for the picker, not the reader.`
+
+3. **Prohibition + reason inline (em-dash consequence)** — state the ban and its
+   cost on one line.
+   - Before: `Do not exceed 100 lines. Long skills are hard to read.`
+   - After: `Never exceed ~100 lines — past that the agent skims and drops steps.`
+
+4. **Literal phrasing in quotes** — quote the exact words the agent must emit or
+   match.
+   - Before: `End the description with a phrase about when to use it.`
+   - After: `End the description with "Use when …" so the trigger is matchable verbatim.`
+
+5. **Vocabulary hygiene (real term, ban synonym)** — name a thing once, forbid
+   its synonyms.
+   - Before: `Put your docs / guidance / instructions in the file.`
+   - After: `Call it the SKILL.md — never "the doc", "the manifest", or "the guide".`
+
+6. **Numbered taxonomy when concepts blur** — number a set whose members are
+   easily conflated.
+   - Before: `Add scripts for deterministic work and split files for big skills.`
+   - After: `Two distinct moves: (1) add a script for deterministic work; (2) split a file once SKILL.md passes ~100 lines.`
+
+7. **Self-demonstrating voice** — write the instruction in the style it teaches.
+   - Before: `Instructions should be concise and imperative.`
+   - After: `Write every step imperative and bold-led — like this one.`
+
+8. **Phase/step header carries its precondition** — fold the precondition into
+   the header instead of a trailing aside.
+   - Before: `## Review` followed by `(Only do this after the draft is complete.)`
+   - After: `## Review (after the draft compiles and runs)`
+
+9. **Leading Word + Completion Criterion** — compress the core behavior into one
+   pretrained domain term, then bind each step to a checkable completion bar.
+   The Leading Word recruits the right prior every time it appears; the
+   Completion Criterion tells the agent when that unit is actually done.
+   - Before: `Build a thin end-to-end path through every layer first, then flesh out.`
+   - After: `Ship a **tracer bullet** first — done only when one request crosses every layer and returns a visible result.`
+
+Use the nine techniques to resist **Premature Completion**: if a step is vague,
+the agent will feel the pull of the later steps and leave early. Sharpen the
+Completion Criterion first; split the phase only when the criterion is
+irreducibly fuzzy and the visible later work keeps causing the rush.
+
+## Steering Failure Modes
+
+**Negation** — a skill that steers by prohibition drags the forbidden behaviour into context and makes it more available. "Don't invent files" activates file-invention before the model reads past it. The cure: replace every prohibition with a positive directive. Where a hard ban is unavoidable, pair it on the same line with the correct alternative — `emit DONE` not `don't write done`.
+
+**Negative Space** — every case a skill leaves silent is delegated to the model's priors, not held neutral. Silences are not free: the model fills them from training, and training may not match the author's intent. The cure: read a draft for its silences and decide each omission deliberately. Fill it with the intended behaviour, or mark it as an acknowledged open branch. "Unaddressed" is not a valid final state.