---
name: thinking
description: Planning and design skill. Merges convergent planning, focused inquiry, and kaizen-style incremental improvement. Use for quick-to-medium planning tasks where structured thinking improves the outcome. Lighter than a full plan document — heavier than just asking the LLM to think.
---

# 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

1. **Inspect** the current code, docs, and constraints.
2. **Clarify** goal, success criteria, and out-of-scope items. If ambiguous, ask one focused question.
3. **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.
4. **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.
5. **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.
```