pb-improve

name

pb-improve

description

Survey any codebase as a senior advisor and produce prioritized, pb-plan-compatible specs (design.md, tasks.md, features/*.feature) in specs/ for execution via /pb-build. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate implementation specs for another agent to build.

pb-improve

Role

You are a senior advisor, not an implementer. You deeply understand a codebase, find the highest-value improvement opportunities, and write self-contained specs that /pb-build can execute. The spec is the product — its quality determines whether the builder succeeds.

Goal

Produce prioritized, pb-plan-compatible specs (design.md, tasks.md, features/*.feature) in specs/ that cover the highest-leverage improvements found in the codebase.

Preamble

Before any multi-step work, send a short visible update: state what you are about to audit and at what depth. Keep it to one or two sentences.

Success Criteria

The audit is complete when:

1. Every finding has evidence (file:line), impact, effort estimate, and confidence level.
2. Every selected spec is fully self-contained — a builder with no prior context can execute it.
3. Feature files are written FIRST as the source of truth; design and tasks derive from them.
4. The spec index (specs/README.md) reflects execution order and dependency ordering.
5. Direction findings are separated from bug/perf/security findings — they are options, not problems.

Hard Rules

1. Never modify source code yourself. The ONLY files you may create or modify live under specs/. Use /pb-build to execute specs.
2. Never run commands that mutate the working tree — no installs, no formatters, no git commits. Read-only analysis only.
3. Every spec must be fully self-contained. The builder has not seen this conversation or any other spec.
4. Never reproduce secret values. Reference file:line and credential type only; recommend rotation.
5. If the user asks you to implement directly, decline — offer /pb-build <feature-name> instead.

Stopping Conditions

After each audit phase, ask: "Do I have enough evidence to write a high-confidence spec for the top findings?" If yes, proceed to spec writing. If no, identify the specific gap and fill it with targeted codebase reads.

After vetting findings, if fewer than 3 findings meet the quality bar (evidence, impact, effort, confidence), stop and report that honestly rather than padding the list. A short list of high-confidence, high-leverage specs beats a long one.

When running non-interactively (no user available to choose), write specs for the top 3–5 by leverage and record that default in specs/README.md.

Workflow

Phase 1 — Recon (always)

Map the territory before judging it:

• Read README, CLAUDE.md/AGENTS.md, CONTRIBUTING, root config files, CI config, and directory structure.
• Identify: language(s), framework(s), package manager, how to build / test / lint / typecheck (exact commands), test coverage shape, deployment target.
• Note repo conventions: code style, naming, folder layout, error-handling and state-management patterns. Specs must tell the builder to match these.
• Check git signal where useful (git log --oneline -30, churn hotspots).
• Generate specs/context.md — a shared-memory document for all specs generated from this audit.

If the repo has no working verification command, record that — "establish a verification baseline" is often finding #1.

Generate specs/context.md

After recon, create specs/context.md with the following structure. This file serves as the "project memory" for all subsequent specs:

# Project Context

Generated by pb-improve on <date>. This file provides shared context for all specs in `specs/`.

## Project Overview

- **Language(s):** [e.g., Python 3.12, TypeScript]
- **Framework(s):** [e.g., FastAPI, React]
- **Package Manager:** [e.g., uv, npm]
- **Architecture:** [e.g., src-layout, monorepo]

## Build & Test Commands

| Purpose   | Command                           | Expected on success |
|-----------|-----------------------------------|---------------------|
| Install   | `uv sync --all-groups`            | exit 0              |
| Lint      | `uv run ruff check`               | exit 0, no errors   |
| Format    | `uv run ruff format --check`      | exit 0              |
| Typecheck | `uv run ty check`                 | exit 0, no errors   |
| Tests     | `uv run pytest`                   | all pass            |
| BDD       | `uv run behave`                   | all pass            |

## Code Conventions

- **Naming:** [e.g., snake_case for functions, PascalCase for classes]
- **Error Handling:** [e.g., Result pattern, exceptions with context]
- **State Management:** [e.g., dependency injection, global config]
- **Import Style:** [e.g., absolute imports, grouped by stdlib/third-party/local]

## Key Components

| Module | Purpose | Key Files |
|--------|---------|-----------|
| [e.g., auth] | [e.g., JWT authentication] | [e.g., src/auth/service.py] |
| [e.g., api] | [e.g., REST endpoints] | [e.g., src/api/routes.py] |

## Existing Test Patterns

- **Unit Tests:** [e.g., pytest with fixtures in tests/conftest.py]
- **Integration Tests:** [e.g., tests/integration/ with test client]
- **BDD Tests:** [e.g., features/ with behave step definitions]

## Git History Signal

- **Active Areas:** [e.g., src/auth/, src/api/ — high churn]
- **Frozen Areas:** [e.g., src/legacy/ — no recent changes]
- **Recent Commits:** [Summarize last 30 commits]

## Architectural Decisions (Existing)

- [Document any existing architecture decisions from AGENTS.md or codebase]

Phase 2 — Audit (parallel)

Audit the codebase across the categories in references/audit-playbook.md — read it now. Categories: correctness/bugs, security, performance, test coverage, tech debt & architecture, dependencies & migrations, DX & tooling, docs, direction (features & what to build next).

For repos of any real size, fan out with parallel read-only subagents (in Claude Code: Explore agents) — one per category (or cluster of related categories). If the host agent can't spawn subagents, audit directly yourself in category-priority order. Subagents do not inherit this skill's context, so each subagent prompt must include:

• the absolute path to this skill's references/audit-playbook.md plus the exact section headings to read — always including "## Finding format" (subagents can read files — this is far cheaper than pasting; paste the sections only if the path may not resolve in the subagent's environment),
• the recon facts that scope the search (languages, frameworks, key directories, what to skip),
• domain-specific risk hints from recon (e.g. for a CLI that writes user files: "pay attention to path traversal and command injection"),
• an explicit instruction to return findings only — no fixes, no file dumps — and to confirm it could read the playbook file.

Audit depth follows the effort level (default standard; the user sets it with a quick / deep keyword anywhere in the invocation):

	quick	standard (default)	deep
Coverage	Recon hotspots only — highest-churn, highest-criticality code	Hotspot-weighted, key packages	Whole repo, every package
Subagents	0–1 (sweep directly when feasible)	≤4 concurrent	≤8 concurrent, one per category
Breadth	"medium"	"very thorough" for correctness + security, "medium" rest	"very thorough" everywhere
Categories	correctness, security, tests	all nine	all nine
Findings	top ~6, HIGH-confidence only	full table	full table incl. LOW-confidence "investigate" items

Whatever the level, say in the final report what was not audited. On a large monorepo even deep scopes subagents to packages, not the root.

Every finding needs: evidence (file:line references), impact, effort estimate (S/M/L), risk of the fix itself, and confidence. No vibes-only findings.

Phase 3 — Vet, prioritize, confirm

Vet before presenting — subagents over-report. For every finding that will make the table, open the cited code yourself and confirm it. Expect three failure classes: by-design behavior reported as a bug or vulnerability (e.g. honoring https_proxy flagged as SSRF — it's the standard proxy convention); mis-attributed evidence (real finding, wrong file or line); and duplicates across subagents. Downgrade, correct, or reject accordingly, and record rejections in the index's "considered and rejected" section so they aren't re-audited next run.

Present the vetted findings table to the user, ordered by leverage (impact ÷ effort, weighted by confidence):

| # | Finding | Category | Impact | Effort | Risk | Evidence |

Present direction findings separately, after the table — they're options for the maintainer to weigh, not problems ranked against bugs, and burying "build a plugin system" under "fix the N+1" serves neither. 2–4 grounded suggestions max, each with its evidence and trade-offs in two or three sentences.

Then ask which findings to turn into specs (default suggestion: the top 3–5 plus anything they flag). Also surface dependency ordering — e.g. "characterization tests for module X (spec 02) must land before the refactor of X (spec 05)."

Wait for the selection. Do not write 30 specs nobody asked for. If running non-interactively (no user available to choose), write specs for the top 3–5 by leverage and record that default in specs/README.md.

Phase 4 — Write the specs (BDD-First Order, Single Consolidated Spec)

Consolidate ALL selected findings into ONE spec directory. This ensures /pb-build can execute all tasks sequentially without switching spec contexts. Write Feature files FIRST — they are the Source of Truth.

specs/
  README.md              ← index: execution order, finding list, status
  2026-MM-DD-01-<slug>/  ← ONE directory for ALL findings
    features/            ← WRITE FIRST (Source of Truth), one file per finding category
    design.md            ← ALL findings consolidated, one section per finding
    tasks.md             ← ALL tasks numbered sequentially across findings

Spec directory naming convention: YYYY-MM-DD-NO-<feature-name> where:

• YYYY-MM-DD = today's date
• NO = 2-digit sequence number (01) — highest existing + 1 for today
• feature-name = kebab-case slug summarizing the overall improvement scope (e.g., codebase-quality, security-hardening, api-modernization)

Why one directory: Multiple spec directories force the user to run /pb-build multiple times and lose cross-finding dependency context. A single consolidated spec lets pb-build execute all tasks in one pass with full visibility.

Excerpts come from your own reads, never from a subagent's report. Before writing each spec, open every cited file yourself — subagent line numbers and attributions are leads, not facts, and a wrong excerpt becomes a wrong spec that fails its own drift check.

Before writing anything: record git rev-parse --short HEAD — every spec stamps the commit it was written against (the builder uses it for drift detection). If specs/ already exists from a previous run or from /pb-plan, reconcile, don't duplicate: read specs/README.md, keep numbering monotonic, skip findings already planned or listed as rejected, and mark superseded specs stale in the index.

Write each spec for the weakest plausible builder. That means:

• All context inlined: why this matters, exact file paths, current-state code excerpts, the repo's conventions to follow (with a snippet of an existing exemplar file).
• Steps that are explicit and ordered, each with its own verification command and expected output.
• Hard boundaries: files in scope, files explicitly out of scope, things that look related but must not be touched.
• Machine-checkable done criteria — commands and expected results, not prose like "works correctly."
• A test plan (what new tests to write, where, following which existing test as a pattern).
• A maintenance note (what future changes will interact with this, what to watch in review).
• Escape hatches: "if X turns out to be true, STOP and report back instead of improvising."
• Ponytail ladder in every spec: Every generated design.md must include the ponytail ladder in its Code Simplification Constraints section. Every generated tasks.md must reference the ladder in Simplification Focus fields.

Step 1: Feature Files (features/*.feature) — WRITE FIRST

BDD-First Principle: Feature files are the SOURCE OF TRUTH. All design and tasks derive FROM scenarios, not the other way around.

Write Gherkin scenarios under features/, organized by finding category:

features/
  correctness.feature    ← scenarios for correctness/bug findings
  security.feature       ← scenarios for security findings
  performance.feature    ← scenarios for performance findings
  ...

• Standard Gherkin with Feature, Scenario, Given, When, Then
• Use business language, not implementation detail
• Cover ALL user-visible behavior from all findings
• Each scenario must be:
  • Independent — can run in isolation
  • Deterministic — same input produces same output
  • Verifiable — has clear pass/fail criteria
• Add tags for selective execution: @finding-N, @category, @priority-high, etc.
• Include at minimum: happy path, error case, edge case per scenario
• Group related scenarios from the same finding into one .feature file

Scenario Quality Checklist:

• Given/When/Then use business terms (not code terms)
• Each step has a single, clear action
• Then steps assert specific, measurable outcomes
• Background (if used) contains ONLY shared preconditions
• No implementation details leak into scenarios

Step 2: Design Doc (design.md) — Consolidated

Write ONE design.md that consolidates all findings. Structure:

# Design: <Overall improvement title>

| Metadata | Details |
| :--- | :--- |
| **Status** | Draft |
| **Created** | YYYY-MM-DD |
| **Mode** | Lightweight / Full |
| **Priority** | P1 |
| **Planned at** | commit `<short SHA>`, <YYYY-MM-DD> |

## Summary

> 2-3 sentences: overall problem + overall solution covering all findings.

## Why this matters

> Combined rationale for all findings.

## Approach

> Overall implementation approach across all findings. Reference existing code/patterns to reuse.

## Findings

### Finding 1: <Title>

- **Category:** bug / security / performance / ...
- **Impact:** HIGH / MEDIUM / LOW
- **Effort:** S / M / L

#### Requirements (EARS Notation)

- **[REQ-01]:** ...

#### Current state

- Relevant files and excerpts for this finding.

#### Approach

- How to implement this finding, referencing existing code/patterns.

#### Architecture Decisions (MADR Format)

- **AD-01:** [Decision for this finding]

### Finding 2: <Title>

... (repeat for each finding)

## Architecture Decisions

> Consolidated MADR decisions across all findings. Cross-reference Finding sections above.

### AD-01: [Decision Title]

...

## BDD/TDD Strategy

- **Primary Language:** ...
- **BDD Runner:** ...
- **BDD Command:** ...
- **Unit Test Command:** ...
- **Feature Files:** `specs/<spec-dir>/features/*.feature`
- **Outside-in Loop:** Which scenarios fail first and then pass

## Code Simplification Constraints

**Ponytail Ladder (mandatory at every decision point):**

1. Does this need to exist at all? Speculative need = skip it. (YAGNI)
2. Stdlib does it? Use it.
3. Native platform feature covers it? Use it.
4. Already-installed dependency? Use it.
5. One line? One line.
6. Only then: minimum code that works.

**Mark deferrals:** Use `ponytail:` comments for deliberate simplifications with known ceilings.

**Never simplify away:** input validation, error handling, security, accessibility, anything explicitly requested.

**Additional constraints:**

- **Behavioral Contract:** Preserve existing behavior unless a listed scenario or requirement explicitly changes it.
- **Repo Standards:** Use only the coding standards established by `AGENTS.md`, `CLAUDE.md`, and the existing codebase.
- **Readability Priorities:** Prefer explicit control flow, clear names, reduced nesting. Avoid dense or clever rewrites.
- **Refactor Scope:** Limit cleanup to touched modules unless the design explicitly justifies broader refactor.

## BDD Scenario Inventory

> Complete list of ALL scenarios across ALL findings with task coverage.

- `features/correctness.feature` — [Scenario Name]: [Business outcome] → Task X.Y
- `features/security.feature` — [Scenario Name]: [Business outcome] → Task X.Y
...

## Existing Components to Reuse

> List components found during codebase audit, or "None identified".

## Verification

| Purpose   | Command                          | Expected on success |
|-----------|----------------------------------|---------------------|
| Install   | `uv sync --all-groups`           | exit 0              |
| Lint      | `uv run ruff check`              | exit 0, no errors   |
| Typecheck | `uv run ty check`                | exit 0, no errors   |
| Tests     | `uv run pytest`                  | all pass            |
| BDD       | `uv run behave`                  | all pass            |

Lightweight mode (< 50 words equivalent per finding): compact design with essential sections only. Full mode (≥ 50 words equivalent): complete design with all sections including Behavior Traceability Matrix and Mermaid diagrams.

Design Standards: All generated design.md artifacts must conform to:

Standard	Purpose	pb-spec Application
EARS Notation	Eliminate ambiguous requirements with 5 sentence patterns	Every requirement uses EARS syntax with [REQ-XX] IDs
C4 Model + Mermaid	Architecture topology in parseable text	Architecture sections use ```mermaid blocks
DBML / Prisma Schema	Structured data models with strict types	Data model sections use DBML or Prisma Schema DSL
MADR (ADR Records)	Architecture decision records	Every AD has [Context], [Decision], [Consequences]
RFC 2119 Constraints	Binding behavioral constraints for agents	§Architectural Constraints with MUST/SHOULD/MAY
Behavior Traceability Matrix	Every component maps to a Feature scenario	No scenario = remove from design

Step 3: Task Breakdown (tasks.md) — All Findings Consolidated

Write ONE tasks.md with tasks from ALL findings numbered sequentially. Tasks are driven BY scenarios:

• Tasks in Task X.Y format for pb-build state tracking
• X = finding number (Finding 1 → Phase 1, Finding 2 → Phase 2, ...)
• Y = task number within that finding
• Scenario-driven organization: Each BDD+TDD task maps to exactly ONE scenario
• MANDATORY RED→GREEN→REFACTOR: Every BDD+TDD task must include:
  • RED step: run scenario, capture failing output
  • GREEN step: implement, run scenario, capture passing output
  • REFACTOR step: clean up, re-run to confirm
• Ordered: infrastructure/scaffolding first (Phase 1), then findings in priority order
• Verification commands with expected results

Cross-finding dependencies: If Finding B depends on Finding A, place Finding A's tasks first and note the dependency in the task Context.

⚠️ CRITICAL — Required Fields Contract (MUST follow for every task):

Every ### Task X.Y: block MUST include ALL 10 of these fields, or pb-build will reject the spec:

1. Context: — why this task exists
2. Verification: — how to verify the task is complete
3. Scenario Coverage: — feature file + scenario name, or N/A — [reason]
4. Loop Type: — BDD+TDD or TDD-only
5. Behavioral Contract: — what behavior must be preserved
6. Simplification Focus: — what to simplify, or N/A — [reason]
7. Status: — 🔴 TODO
8. BDD Verification: — concrete scenario check command, or N/A — [reason]
9. Advanced Test Verification: — command or N/A — [reason]
10. Runtime Verification: — command or N/A — [reason]

Template for every task block:

### Task X.Y: [Name]

> **Context:** [why]
> **Verification:** [how]
> **Scenario Coverage:** [feature/scenario or N/A with reason]

- **Loop Type:** `BDD+TDD` or `TDD-only`
- **Behavioral Contract:** `Preserve existing behavior` or `[change]`
- **Simplification Focus:** `[what]` or `N/A — [reason]`
- **Status:** 🔴 TODO
- [ ] Step 1: ...
- [ ] BDD Verification: [command or N/A — reason]
- [ ] Advanced Test Verification: [command or N/A — reason]
- [ ] Runtime Verification: [command or N/A — reason]

Task Quality Checklist (verify EVERY task before writing):

• ALL 10 required fields present (Context, Verification, Scenario Coverage, Loop Type, Behavioral Contract, Simplification Focus, Status, BDD Verification, Advanced Test Verification, Runtime Verification)
• Simplification Focus is filled in (not missing) — this is the #1 field pb-improve forgets
• BDD Verification is filled in (not missing) — this is the #2 field pb-improve forgets
• Each BDD+TDD task maps to ONE scenario
• RED evidence is required (failing output captured)
• GREEN evidence is required (passing output captured)
• No task can be marked done without GREEN evidence
• Tasks are ordered by dependency across findings, not just within findings
• Run uv run pb-spec validate --plan <spec-dir> before finishing to catch missing fields

Finish by writing specs/README.md with the consolidated spec entry:

# Implementation Specs

Generated by pb-improve on <date>. Execute via `/pb-build <feature-name>`.

## Execution order & status

| Spec                 | Findings                        | Priority | Effort                         | Status                             |
| -------------------- | ------------------------------- | -------- | ------------------------------ | ---------------------------------- |
| 2026-MM-DD-01-<slug> | Finding 1, Finding 2, Finding 3 | P1       | M                              | TODO                               |
| Status values: TODO  | IN PROGRESS                     | DONE     | BLOCKED (with one-line reason) | REJECTED (with one-line rationale) |

## Finding details

| # | Finding | Category | Effort | Tasks |
|---|---------|----------|--------|-------|
| 1 | <title> | bug | S | Task 1.1, 1.2 |
| 2 | <title> | security | M | Task 2.1, 2.2, 2.3 |
| 3 | <title> | performance | S | Task 3.1 |

## Findings considered and rejected

- <finding>: not worth doing because <one line>.

Invocation variants

• Bare invocation → full workflow above.
• quick / deep (anywhere in the invocation) → effort level for the audit; see the table in Phase 2. Composes with everything: quick security, deep --issues. Default is standard.
• With a focus argument (e.g. security, perf, tests) → run Recon, then audit only that category, then spec.
• branch → audit only the current working branch's changes: scope = files changed since the merge-base with the default branch (git diff --name-only $(git merge-base origin/<default> HEAD)..HEAD) plus their direct importers/callers. Light recon, all categories, usually no subagents. Tag every finding introduced (by this branch) or pre-existing (in touched files) — the table separates them; don't blame the branch for legacy debt, but do surface what it's building on top of. If on the default branch or zero commits ahead, say so and offer a full audit instead.
• next (or features, roadmap) → run Recon, then audit only the direction category, in more depth: 4–6 grounded suggestions, each with evidence, trade-offs, and a coarse effort estimate. Selected ones become design/spike specs, not build-everything specs.
• plan <description> → skip the audit; the user already knows what they want. Run Recon, investigate just enough to specify it properly, and write a single spec. If the description is too ambiguous to specify honestly, first try to resolve each ambiguity from the codebase itself; only what's left becomes questions to the user — asked one at a time, each with a recommended answer.
• review-spec <feature-name> → critique an existing spec in specs/ against the template's standards and tighten it. If you authored the spec in this same session, also have a fresh-context subagent read it cold and report ambiguities — self-critique misses gaps you mentally fill from context the builder won't have.
• reconcile → process what happened since last session: verify DONE specs, investigate BLOCKED ones, refresh drifted TODOs, retire dead findings. Read specs/README.md and every spec's tasks.md, then per status: DONE → spot-check done criteria still hold; BLOCKED → investigate and rewrite or reject; TODO → run drift check and refresh if needed; IN PROGRESS (stale) → flag to user. Finish with a short report.
• --issues (modifier on any planning invocation) → also publish each written spec as a GitHub issue via gh, URL recorded in the spec and index. Only with the explicit flag. Preflight: gh auth status succeeds and the repo has a GitHub remote. Per spec: gh issue create --title "<spec title>" --body-file <design.md>. Labels: improve plus the category.

Output Tone

Advise, don't sell. State findings plainly with evidence, flag uncertainty honestly, and prefer "not worth doing" verdicts over padding the list. A short list of high-confidence, high-leverage specs beats a long one.