plan-grill-codex

Files (1)

• SKILL.md

SKILL.md (first lines)

# Plan-Grill-Codex

A high-stakes planning skill for this harness: **load context first, grill only the real unknowns, then have Codex attack the plan before code is written.**

This adapts the `grill-me-codex` idea to the harness's existing context model:

- `docs/VISION.md` is the stable north star and governs on conflict.
- `docs/STATUS.md` is the current tactical snapshot.
- `CLAUDE.md` contains repo-specific conventions and operating rules.
- `CONTEXT.md` / `CONTEXT-MAP.md` define domain language and bounded contexts when present.
- `docs/decisions/` or `docs/adr/` hold durable architecture decisions.
- `rpi/<feature>/research/` and `rpi/<feature>/plan/` may already contain product/engineering planning docs.

The point is to avoid asking the user questions that the repo already answers, while still forcing clarity on decisions that are genuinely open.

---

## When to use

Use this when the plan is expensive to get wrong:

- auth, roles, permissions, trust boundaries
- database schemas, migrations, data ownership, irreversible storage choices
- concurrency, background jobs, queues, race-prone flows
- payment/billing/financial or operationally sensitive paths
- agent/tool orchestration where failures are hard to observe
- major UI/product workflow decisions
- changes likely to take more than ~2 hours or touch multiple subsystems
- anything where the user says "grill this", "stress-test this", "have Codex attack the plan", or similar

Do **not** use this for:

- tiny bug fixes, copy edits, CSS tweaks, docs-only polish
- already-written code review of a branch/diff: use `codex-review`
- ordinary in-Claude review: use `code-review` / `requesting-code-review`
- full RPI planning ceremony unless the user explicitly wants this as an added gate

---

## Mode selection

Default mode is **direct Codex loop** if Codex CLI is installed/authenticated.

Switch to **prompt-only mode** when the user says "don't run Codex", "give me a prompt", "paste-ready", "manual Codex", or "I'll run Codex myself". Prompt-only mode still creates a strong plan but outputs a Codex prompt instead of invoking `codex`.

If using direct mode, Codex must be read-only every round. Never let Codex write files.

---

## Act 0 — Context stack preload

Before asking the user anything, inspect the project's context stack. Read only files that exist; skip missing files silently unless their absence changes the plan.

### 0a. Resolve project root and task

- Use the current working directory as the project root unless the user gave a path.
- Identify the task/feature being planned.
- If the task is not clear, ask one clarifying question and stop until answered.

### 0b. Read stable/top-level context first

Read in this order:

1. `docs/VISION.md` — stable purpose/principles; governs on conflict.
2. `docs/STATUS.md` — current focus, working state, next steps, open questions.
3. `CLAUDE.md` — project-specific conventions, constraints, command routing.
4. `README.md` — setup, architecture, user-facing framing.
5. Manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, etc. for stack reality.

### 0c. Read domain/context files

- If `CONTEXT-MAP.md` exists, read it and identify the relevant context(s).
- If a root `CONTEXT.md` exists, read it.
- If context-specific `CONTEXT.md` files exist under `src/`, `apps/`, `packages/`, or similar, read only the relevant ones.
- Treat `CONTEXT.md` as domain language/glossary, not implementation spec.

When the user uses a fuzzy or conflicting term, check the context docs first. If the docs define the term, use the canonical term and call out the mismatch.

### 0d. Read decisions and planning artifacts

Read or skim:

- `docs/decisions/README.md` and relevant ADRs under `docs/decisions/`
- `docs/adr/` if the project uses that instead
- `docs/log/` only if STATUS is stale or the task mentions recent history
- `rpi/<feature>/research/RESEARCH.md` and `rpi/<feature>/plan/*.md` if the task maps to an RPI feature folder
- existing `PLAN.md` / `PLAN-REVIEW-LOG.md` if present for this task

### 0e. Build an internal context brief

Summarize internally:

- **North star / principles:** what VISION requires or forbids.
- **Current state:** what STATUS says is active, working, next, blocked.
- **Relevant domain terms:** canonical language from CONTEXT files.
- **Prior decisions:** ADRs this plan must honor or supersede.
- **Existing plan/research:** if RPI docs already exist, what they decided.
- **Unknowns:** only questions not answered by files or code.

Do not dump all context to the user. Use it to ask better questions and produce a better plan.

---

## Act 1 — Grill the real unknowns

Interview the user relentlessly, but **only where the context stack cannot answer for itself**.

Rules:

1. Ask one question at a time.
2. For every question, include your recommended answer and why.
3. If code/docs can answer the question, inspect them instead of asking.
4. Tie questions back to VISION, STATUS, CONTEXT, ADRs, or RPI docs when relevant.
5. Surface conflicts directly:
   - "VISION says X, but this plan implies Y. Should we change the plan or amend VISION?"
   - "ADR-0004 chose X; this plan needs Y. Is this a superseding decision?"
   - "CONTEXT defines `Member` as X, but you seem to mean Y. Which term should we use?"
6. Do not let the interview sprawl. If the answer is low-risk or reversible, choose a reasonable default and label it.

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness