philoserf/claude-code-config

Review this codebase for bugs, design issues, and code cleanliness problems. Be specific and cite file paths and line numbers.

Scope the review to `$ARGUMENTS` if provided, otherwise review the entire project. Examples: `src/auth/`, `lib/api.ts`, `security`, `tests/`.

Skip vendored dependencies, build output, generated/minified code, and lockfiles (e.g. `node_modules/`, `dist/`, `build/`, `vendor/`, `*.min.js`, `package-lock.json`, `go.sum`).

## Output

Findings go to `.issues/` and the overview to `.issues/000-audit.md`, following
[issues-protocol.md](references/issues-protocol.md) — read it before writing anything. It
is the canonical copy shared across the `code-*` review skills, and it defines the
file layout, the finding format and severity scale, the dedup checks against `.issues/` and
GitHub, and what to do on a re-run.

Review this codebase and advise on refactoring to reduce, simplify, remove, and reorganize. The goal is less code and fewer concepts, not tidier code.

Scope the review to `$ARGUMENTS` if provided, otherwise review the whole project. Examples: `src/api/`, `the test suite`, `lib/parsers/`.

Skip vendored dependencies, build output, generated code, and lockfiles (`node_modules/`, `dist/`, `vendor/`, `*.min.js`, `go.sum`).

## First, establish the license to delete

This skill assumes **sole-owner code with no backward-compatibility constraints**. That assumption is what makes aggressive deletion the right call, so check it before leaning on it: look for a published package name, semver tags, a CHANGELOG, a documented public API, or `deprecated` markers that imply someone downstream. If you find signs of external consumers, say so explicitly and mark which recommendations the constraint blocks — don't silently soften the whole review.

## What to look for

**Abstractions that don't earn their keep.** An interface with one implementation. A factory that constructs one thing. A base class extended once. A strategy pattern over two branches that never grew to three. A config object for parameters that are always the same. Count the call sites — an abstraction with one caller is a function with extra steps.

Conduct a deep technical review of this codebase with the goal of determining how it should
be refactored.

**Do not begin by changing code.** First understand the system as it exists: what problem it
solves, how it is organized, what constraints appear to have shaped it, and where its
current design helps or hinders future work. This is an architectural and implementation
review, not a linting exercise.

Do not assume that more abstraction, more layering, more interfaces, more files, or more
design patterns constitute improvement. Prefer the simplest design that accurately expresses
the domain and satisfies the real requirements.

Scope the review to `$ARGUMENTS` if provided, otherwise treat the whole repository as in
scope. Examples: `the storage layer`, `cmd/`, `the plugin system`.

Build and express a theory of this codebase in the sense Peter Naur meant in "Programming as Theory Building": not a summary of what files exist, but an account of the understanding a competent maintainer would need to hold in mind to modify this system without damaging its conceptual integrity.

Scope the investigation to `$ARGUMENTS` if provided, otherwise treat the whole repository as in scope. Examples: `the scheduler`, `src/billing/`, `the plugin system`.

Skip vendored dependencies, build output, generated code, and lockfiles (`node_modules/`, `dist/`, `vendor/`, `*.min.js`, `go.sum`).

## Phase one — investigation

Read widely before you read deeply.

1. **Orient.** Entry points, build configuration, top-level module structure. Enough to know what runs and in what order.
2. **Follow the grain.** Trace a few representative flows end-to-end. A flow you can follow from input to durable effect teaches more than ten files skimmed.
3. **Read the tests.** They record which behaviors the authors considered load-bearing. A behavior with an exhaustive test suite and a behavior with none are telling you different things.
4. **Read the history.** Recent commits, design notes, ADRs, long comments. These are the decisions the authors thought worth recording — and the ones they kept revisiting.

Read the source and produce a linear walkthrough that explains how the code works in detail. Write it to `WALKTHROUGH.md` in the repo root.

## Workflow

1. **Scope** — If a scope/focus argument is given, limit source reading and coverage to that area.
2. **Write** — If `WALKTHROUGH.md` already exists, ask the user whether to overwrite it or extend it before writing anything. Then alternate commentary and snippets, starting from the entry points and following the call chain.
3. **File what you found** — see [Findings](#findings). Do not close the document with an index of findings: the walkthrough ends with its last section, and the findings live in `.issues/`. Where the prose cites an issue, observe the protocol's rule on durable references — `WALKTHROUGH.md` is a standing document. When reporting, point the user at the file and list the findings you filed.

## Findings

Tracing code end to end surfaces things a reader of the finished walkthrough should not have to rediscover. File them to `.issues/` following [issues-protocol.md](../code-audit/references/issues-protocol.md) — the canonical copy shared across the `code-*` review skills — with `**Source:** code-walkthrough`. What qualifies:

- **Prose in an existing `WALKTHROUGH.md` that the code no longer supports.** Nothing checks this document — a rename or a deletion leaves the narrative describing something that is gone, and it stays that way until a reader trips over it. You are reading the source and the prose side by side, which almost nobody else does, so this is the finding this skill is best placed to catch. Verify each claim against the code and cite both sides.
- **Code that resists linear explanation.** Where the narrative had to jump, backtrack, or ask the reader to hold two things in mind at once, the call chain is telling you something about the structure. Say where the order broke down.

# Copy Editor

### Step 0: Handle Input

If `$ARGUMENTS` is a file path, `Read` it. If it is prose pasted inline, edit that directly. If it is empty, ask for the piece.

Never write back to the source file unless asked. Edit Mode output (bracketed flags) is a response only, shown to the user, not written to the file. Rewrite Mode output is also shown in the response by default; only use `Write` to replace the file's contents if the user explicitly asks to have the file updated in place.

### Step 1: Detect the Register

Before editing, read the full piece and identify its register. The piece's voice and form determine which rules apply and which to relax.

| Register              | Characteristics                                                           | Adjust                                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |

# Ship one issue

One issue in, one merged PR out. The mechanics — gate, push, open, merge — are a script, so
nothing reaches the remote without passing the gate. Everything else is judgment.

## 1. Read the issue before touching anything

Re-check its claims against `HEAD`. A filed issue describes a tree that has moved; fixing
what it says rather than what is there is how a PR ends up reverting someone's work.

`~/.claude/skills/issue-verify/scripts/issue-facts.sh <N>` prints the file and symbol rows
and the commits that have touched them since filing. If the finding is already fixed, say
so and close the issue — do not manufacture a change.

# Issue triage

The step between filing issues and working them. A finding written to `.issues/` and pushed
to GitHub arrives with a title, a body and a label; it does not arrive knowing which release
it belongs to, what it waits on, or how severe it really is. This skill supplies that.

Triage is about **placement**, not truth. Whether a finding is still correct is
`issue-verify`'s question, and a freshly filed issue usually has not had time to go stale.

## Start with the audit

```bash
~/.claude/skills/issue-triage/scripts/issue-meta.sh audit [milestone]
```

# Issue verification

An issue is a claim about a tree that has since moved. This skill re-reads each one against
current `HEAD`, decides whether the claim still holds, and writes that decision down where
the next reader will find it — on the issue.

Verification is not agreement. The output is a disposition for every issue looked at, and
"this was fixed three commits ago" is as useful a result as "still stands".

## Gather the facts first

```bash
~/.claude/skills/issue-verify/scripts/issue-facts.sh <N> [N...]
```

# Milestone sweep

One agent per repo under `~/source/philoserf/`, each working its repo end to end in a linked
worktree: verify, triage, pick the next milestone, ship it with `issue-pr`, gate it with
`release-gate`, stop before tagging. You orchestrate and do not touch the repos yourself
while their agents run.

**Run it on `almanac`, from a session started in `~/source/philoserf`.** `almanac` is the
always-on host. Twenty agents report back over an hour or more, and nothing here needs
`sextant`. Starting anywhere else, such as `~/notes`, roots the language server outside the
repos. It then sends a stream of false "module not in workspace" and `undefined:` errors
about files that compile.

## 1. Sync, then list the repos

# Pre-Release Gate

Systematic verification that a repository is ready to tag. Delegates all mechanical checks to a shell script and interprets its output.

## Script location

`~/.claude/skills/release-gate/scripts/release-check.sh`. It resolves the repo root via `git rev-parse --show-toplevel` and operates from there, so invoke it from anywhere inside the working tree.

## Prerequisites

`git`, `jq` and `gh` are always needed. The rest depend on the profile — `bun` for a Node or
Obsidian repo, `go` and `govulncheck` for a Go one, `task` where a Taskfile supplies the
commands. A missing binary makes its check row fail —
diagnose that as a setup gap, not a real gate failure.

# Release

Final step in the release pipeline. Assumes `release-gate` has already passed and the target version has been decided.

This skill follows the **prep-PR pattern**: version bump + CHANGELOG + walkthrough ship as one atomic PR. The tag is applied **after merge**, pointing at the merged commit. Never use a tool that bumps and tags in one step (`npm version`, `bun version`, `hatch version --tag`) — they tag immediately and skip the CHANGELOG and walkthrough entirely.

The workflow is a single linear pass — run the phases in order:

0. Read the plan → 1. Prep branch → 2. Version bump → 3. CHANGELOG → 4. Walkthrough → 5. Build, commit & open PR → **(merge)** → 6. Gate, then tag → 7. Push tag → 8. Release notes → 9. Deploy → 10. Verify

## Prerequisites

Before starting, confirm:

# Release sweep

The shipping half of `/milestone-sweep`. Separate on purpose: the sweep stops before
shipping, and a release is a public step the user takes on purpose.

One `repo-releaser` agent per repo cuts its release with `release-ship`. You find what is
ready, get the list confirmed once, launch the agents, and clean up afterwards.

**Run it on `almanac`, from a session started in `~/source/philoserf`**, for the same reasons
as `/milestone-sweep`.

## 1. Find what is ready

```bash

<!-- Installed by "rex skill setup". Remove it with "rex skill remove". -->

Run `rex __internal skill` and follow the guide it prints. The guide comes from
the installed Rex CLI, so it describes the commands available in that version.

If the command fails, the installed Rex version predates the guide. Start with
`rex whoami --json`, then use `rex --help` and `rex COMMAND --help`.