Thinking
If the repo has an AGENTS.md, read it first for repo conventions.
Adjacent skills: brainstorming (divergent generation) → thinking (convergent planning) → recursive-thinking (adversarial stress-testing) → dream-thinking (retrospective learning).
Use thinking when the main need is to converge on a practical plan. Do not escalate to recursive-thinking unless the decision is high-risk, ambiguous, contentious, or likely to hide important assumptions.
Typical chaining:
- use thinking to converge on a plan
- use recursive-thinking to challenge that plan when risk or ambiguity is high
- use dream-thinking after execution, conflict, or reflection-worthy experience
Default Stance
- understand the current repo shape before proposing changes
- prefer incremental, testable improvements over rewrites — unless the complexity is structural (>3 files or ongoing maintenance burden), in which case compare rewrite cost against compounding workaround cost
- keep plans implementation-ready and decision-complete
- remove unnecessary complexity ruthlessly
Workflow
- Inspect the current code, docs, and constraints.
- Clarify goal, success criteria, and out-of-scope items. If ambiguous, ask one focused question.
- Compare 2-3 approaches when the choice materially affects the outcome.
- Compare on: complexity, risk, reversibility, time-to-implement, dependency count.
- For each rejected approach, state why it lost in one line.
- If only one viable approach exists, say so and skip comparison.
- Choose the approach with the least unnecessary complexity.
- "Narrowest" = fewest behavioral changes, smallest API surface, least cross-cutting risk.
- When narrowest conflicts with quality, prefer quality unless explicitly time-boxed.
- Produce a concrete plan using the output structure below.
Plan Revision
Watch for: blocked on something unanticipated, new constraint discovered during implementation, execution diverging from assumptions. When any fires: update the plan before continuing.
Planning Stop Test
Planning is sufficient when all three are true:
- the next implementation step is concrete
- the main trade-off has been decided or explicitly deferred
- validation is clear enough to detect failure
Focused Inquiry Rules
- ask only questions that materially change the design
- prefer one issue at a time over broad unfocused discovery
- validate assumptions early when they affect architecture or rollout
Kaizen Rules
- make invalid states harder to express
- use the type system, validation, and clear contracts to prevent mistakes
- when modifying a file, fix at most one small adjacent issue — do not refactor unrelated code
Anti-patterns
- inventing weak alternative approaches just to satisfy the comparison step
- asking broad discovery questions that do not change the plan
- producing a plan that sounds organized but leaves the next action ambiguous
- using "narrowest" to justify avoiding necessary quality improvements
Output Structure
Scale to task size.
Small tasks (single file, clear approach):
## Goal
One sentence.
## Approach
What to change and why.
## Validation
How to verify it works.
Medium tasks (multiple files, trade-offs):
## Goal
What we're trying to achieve and what success looks like.
## Constraints
What's out of scope, what must not break.
## Approach Comparison
| Approach | Pros | Cons | Risk |
|----------|------|------|------|
| A | ... | ... | ... |
| B | ... | ... | ... |
Chosen: A, because [reason]. Not B, because [reason].
## Key Changes
By subsystem or file group.
## Validation
Tests, manual checks, or acceptance criteria.
## Assumptions
What we're taking as given. What would invalidate the plan.
Large tasks (cross-cutting, architectural): Medium template plus:
## Phases
Ordered steps with dependencies noted.
## Rollback
What to do if a phase fails.