Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions .claude/skills/plan-review-cycle/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
name: plan-review-cycle
description: Use after writing an implementation plan, before committing. Adversarial review for subagent-readiness — checks ambiguity, context gaps, interpretation drift, cross-task conflicts, and pitfall coverage across minimum 4 rounds.
---

# Plan Review Cycle

Rigorously review an implementation plan for subagent-readiness before
committing. Minimum 3 rounds. If round 3 finds substantive issues,
keep going until clean.

## How to run

### Round structure

Each round reviews the plan against ALL of these dimensions:

**Ambiguity** — Can a subagent reasonably interpret any task description
two different ways? Eliminate every instance. Look for "handle this
correctly," "fix the issue," "update as needed" — replace with specific
behavioral descriptions.

**Context gaps** — Would a subagent starting fresh (no conversation
history) have everything it needs? Check for:
- References to "the bug we discussed" (subagent wasn't in that discussion)
- Implicit knowledge of the codebase structure
- Assumptions about what packages are installed or what patterns exist
- Missing file paths or line numbers

**Interpretation latitude** — Could a subagent "improve" or "enhance"
beyond scope? Look for:
- Tasks that describe a goal without constraining the approach
- Missing "do NOT" boundaries on adjacent code
- Opportunities for a subagent to refactor, rename, or reorganize

**Cross-task dependencies** — Are ordering constraints explicit? Would
a subagent working on Task 3 know it depends on Task 1? Look for:
- Shared files modified by multiple tasks
- Tasks that create types/interfaces consumed by later tasks
- Test fixtures needed across tasks

**Testing pitfalls** — Read `docs/pitfalls/testing-pitfalls.md`. Could
any planned test additions fall into documented pitfalls? Add warnings
to relevant tasks. Common traps:
- Testing mock behavior instead of real behavior
- Missing AOT verification
- Substring assertions instead of structural JSON checks

**Implementation pitfalls** — Read `docs/pitfalls/implementation-pitfalls.md`.
Could any planned implementation fall into documented traps? Common:
- AOT-unsafe types in serialization contexts
- Pre-signed URL auth header leaks
- Hand-built JSON without escaping

### Round execution

For each round:
1. Read the plan end-to-end
2. Check every dimension above
3. Note each finding with location (Task N, specific text)
4. Fix all findings in the plan
5. Record the round number and finding count

### Completion criteria

- Round 1: expect 5+ findings (plans always have gaps on first review)
- Round 2: expect 2-3 findings (residual from fixes in round 1)
- Round 3: expect 1-2 (second-order effects of prior fixes)
- Round 4: if 0 findings, you're done. If any, keep going.
- Round 5+: continue until a round produces 0 findings

If round 1 produces 0 findings, you're not looking hard enough.
Re-read the dimensions and try again.

### After completion

Log observations about plan quality and recurring patterns:

```
/gstack-learn add
```

Type: pattern
Key: plan-review-[slug]
Insight: what patterns emerged, what was most commonly wrong

Commit the reviewed plan.
100 changes: 100 additions & 0 deletions .claude/skills/writing-plans-enhanced/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
---
name: writing-plans-enhanced
description: Use when writing implementation plans for this project. Wraps superpowers:writing-plans with project-specific conventions — plan location, execution strategy recommendation, subagent-proofing requirements, TDD mandates, and pitfall review.
---

# Writing Plans (Enhanced)

Wraps `/superpowers:writing-plans` with project-specific requirements
that prevent subagent failures during execution.

## Step 1: Invoke the base skill

Invoke `/superpowers:writing-plans`. Follow it completely.

Save the plan to `docs/plans/<date>-<slug>-plan.md`
(e.g., `docs/plans/2026-04-08-mcp-tools-plan.md`).

## Step 2: Execution strategy recommendation

When `/writing-plans` presents execution options, recommend one with
reasoning. The three options:

1. **Subagent-driven** (`/superpowers:subagent-driven-development`) —
fresh subagent per task, review between tasks. Best for independent
tasks needing quality gates.
2. **Parallel session** (`/superpowers:executing-plans` in a worktree) —
batch execution with checkpoints. Best for tightly coupled sequential
tasks.
3. **Parallel agents** (`/superpowers:dispatching-parallel-agents`) —
concurrent agents on independent workstreams. Best for 3+ independent
tracks with different files.

Base the recommendation on:
- How much context this session has consumed
- Whether the plan is self-contained enough for a fresh session
- How many tasks are parallelizable vs sequential
- Whether any tasks are risky enough to warrant focused attention

## Step 3: Subagent-proof the plan

Subagents start fresh with zero context. The plan MUST prevent their
predictable failure modes:

### Eliminate ambiguity
For each task, specify:
- Exact files to create or modify
- Exact behavior change (current → desired)
- Exact test to write (input, expected output, edge cases)
- Ordering dependencies with other tasks

### Prevent context gaps
Each task description must be self-contained:
- Include evidence (file:line, what's wrong or what's needed)
- Include the approach (not just "fix the bug" or "add the feature")
- Include architectural context if the task depends on a design choice
- If the task touches shared code, list other callers that must still work

### Prevent interpretation drift
- Where there's one correct approach, state it explicitly
- Where there are multiple valid approaches, pick one and specify it
- Add "do NOT" boundaries where a subagent might over-engineer

### Mandate TDD
Every task MUST include:
```
BEFORE starting work:
1. Invoke /superpowers:test-driven-development
2. Read docs/pitfalls/testing-pitfalls.md
Follow TDD: write failing test → implement → verify green.
```

Every task MUST include:
```
BEFORE marking this task complete:
1. Review tests against docs/pitfalls/testing-pitfalls.md
2. Verify test coverage (error paths? edge cases?)
3. Run tests and confirm green
```

Every logical group of tasks MUST include:
```
After completing this group:
Review the batch from multiple perspectives. Minimum 3 review rounds.
If round 3 still finds issues, keep going until clean.
```

### Review against pitfalls
Read both pitfalls docs and check if any planned work could fall into
documented traps. Add explicit warnings to relevant task descriptions:
- `docs/pitfalls/implementation-pitfalls.md`
- `docs/pitfalls/testing-pitfalls.md`

### Minimize cross-task conflicts
If two tasks touch the same file, put them in the same task or
explicitly sequence them. Parallel subagents editing the same file
create merge conflicts.

## Step 4: Run /plan-review-cycle

After writing the plan, invoke `/plan-review-cycle` before committing.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,6 @@ chats/
# Git worktrees
.worktrees/
.claude/worktrees/

# Serena MCP — local project state, cache, and personal memories
.serena/
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module github.com/scarson/cvert-ops

go 1.26.0
go 1.26.2

require (
github.com/KimMachineGun/automemlimit v0.7.5
Expand All @@ -16,7 +16,7 @@ require (
github.com/golang-jwt/jwt/v5 v5.3.1
github.com/golang-migrate/migrate/v4 v4.19.1
github.com/google/uuid v1.6.0
github.com/jackc/pgx/v5 v5.9.1
github.com/jackc/pgx/v5 v5.9.2
github.com/lib/pq v1.12.3
github.com/pquerna/otp v1.5.0
github.com/prometheus/client_golang v1.23.2
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -111,8 +111,8 @@ github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsI
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
github.com/jackc/pgx/v5 v5.9.1 h1:uwrxJXBnx76nyISkhr33kQLlUqjv7et7b9FjCen/tdc=
github.com/jackc/pgx/v5 v5.9.1/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
github.com/jhillyerd/inbucket v2.0.0+incompatible h1:gTmxV077ktqV4ZbFjB/0rjiTrdsKQGXWUqYKWjoNIrE=
Expand Down
Loading