| name | plan-enforcer-research |
| description | Use before `plan-enforcer-draft` on any non-trivial plan to inspect the actual repo (structure, conventions, git history, relevant existing files) and produce a concrete research brief the drafter consumes, so the plan reflects what the codebase is rather than what sounded reasonable from the request alone. |
Plan Enforcer Research
Before drafting a plan, read the repo. Most plan quality problems
don't come from bad drafting โ they come from drafting against
assumptions about a codebase that doesn't match reality. This skill
spends a few minutes inspecting the actual code and writes down what
it finds, so the drafter has real context to work from.
Distinct from plan-enforcer-discuss: discuss captures
user intent (what the user wants). This skill captures repo
reality (what exists, what conventions apply, what's in the way).
Both inputs feed plan-enforcer-draft. Each is optional; both
together produce the sharpest plans.
When to use
Use this when the plan will:
- Modify code in areas of the repo you haven't read yet
- Add to an existing codebase with conventions you don't know
- Touch integration points (routes, models, middleware) where
consistency matters
- Span more than a handful of tasks (medium + large plans benefit
most)
Skip this when:
- The request is a trivial fix in code you already know
- The user says "skip research" or "I've briefed you already"
- A recent
.plan-enforcer/research.md covers the area
(mtime < 24h, scope overlaps the current request)
What to inspect
Target the information that actually affects plan shape:
- Shape of the repo. Language(s), framework(s), top-level
directory conventions. Run
git ls-files | head -50 equivalent
or list the src/ root. Note build + test commands from
package.json, Cargo.toml, pyproject.toml, etc.
- Existing conventions in the area. If adding a route, read
two existing routes and note their shape (Router factory? inline
app.get? middleware mounting order?). Don't guess.
- Recent git history in related files.
git log --oneline -20
on the target files or directory. Patterns here reveal active
refactors, recent deprecations, and contributor habits.
- Test + config constraints. Which runner? Which lint rules?
Strict TypeScript? Any jest.config or tsconfig
strict flags
that constrain shape?
- Gaps and tribal knowledge. Anything that the drafter would
need to know that isn't in the filenames โ contradictions
between README and code, TODOs in nearby files, recent commits
reverting other work.
Rules
- Produce one file at
.plan-enforcer/research.md. One per project;
overwrite the prior one unless the user says otherwise.
- Cite actual file paths and line numbers when possible. "src/
routes/users.ts uses Router factory" is useful; "uses the Router
pattern" is not.
- Record what you didn't inspect. "Did not read src/db/ because
out of scope for this plan" is helpful context for the drafter.
- Do NOT propose tasks. This skill produces context, not plan.
- Keep output under ~600 words. If you need more, the scope is
probably multiple plans (split the request).
- Quote exact strings from the repo when they matter โ import
statements, function signatures, commit subject lines. Don't
paraphrase convention, show it.
Recommended brief shape
# Research: <short name for the area>
## Repo shape
<1-2 sentences: stack, top-level structure, build+test commands>
## Conventions in the target area
- <observed pattern with file:line reference>
- <observed pattern>
## Recent history (related files)
- <commit sha + subject> โ <one-line what it did>
- <commit sha + subject>
## Constraints discovered
- <test runner, lint rules, strict flags, type guarantees>
- <anything that fails CI if violated>
## Gaps / tribal knowledge
- <contradiction, TODO, recent revert, deprecated pattern>
- <anything the drafter needs to know that isn't in filenames>
## What I did NOT inspect
- <areas explicitly skipped and why>
Anti-patterns
Producing generic advice instead of repo-specific facts is the
failure mode. Smells:
- "Follow existing patterns" with no example โ not helpful
- "Write tests" with no reference to existing test style โ the
drafter will invent one
- More than ~600 words โ either the scope is too broad, or the
author is speculating past what they read
- Any statement about behavior without a file or commit to back it
- Numbered task list in the brief โ that's the drafter's job
Handoff
After writing the brief:
- Tell the user the path (
.plan-enforcer/research.md).
- Summarize the decisions captured in one line per section.
- Offer next step: "want me to draft the plan against this research
(and the discuss packet, if present)?" and wait.
