planning

---
name: planning
description: Use when starting a non-trivial feature, refactor, or multi-file change. Forces structured design thinking before writing any code - brainstorm approaches, get approval, then create a step-by-step implementation plan.
user-invocable: true
argument-hint: "<feature or task description>"
---

# Planning - Design Before Code

Structured workflow for planning implementation before writing code. Prevents wasted effort from diving in without a clear direction.

## When to Use

- New features spanning multiple files or modules
- Refactors touching backend, frontend, or ingestion layers
- Bug fixes where the root cause is unclear
- Any task where the approach isn't immediately obvious

## Workflow

### Phase 1: Understand the Problem

1. **Read before suggesting.** Explore the relevant code, schemas, and tests. Do not propose changes to code you haven't read.
2. **Ask clarifying questions** one at a time. Don't dump a list of 10 questions.
3. **Identify constraints:**
   - Which layers are affected? (Java backend, React frontend, Python ingestion, JSON schemas)
   - Are there existing patterns to follow? (Check similar implementations)
   - Database migration needed? (Flyway in `bootstrap/sql/migrations/`)
   - Schema changes needed? (`openmetadata-spec/` JSON schemas)

### Phase 2: Propose Approaches

Present **2-3 approaches** with trade-offs:

```
## Approach A: [Name]
- How it works: [1-2 sentences]
- Pros: [bullet list]
- Cons: [bullet list]
- Files affected: [list]
- Risk: [low/medium/high]

## Approach B: [Name]
...

## Recommendation: [A or B] because [reason]
```

**Wait for user approval before proceeding.**

### Phase 3: Create Implementation Plan

Once an approach is approved, break it into ordered tasks:

1. Each task should be **completable in a single focused step**
2. Each task must specify:
   - Exact file paths to create or modify
   - What changes to make (not vague descriptions)
   - Verification command (test to run, build to check)
3. Order tasks by dependency — schema changes before model generation, backend before frontend
4. Include a final verification task that runs all relevant tests

**OpenMetadata task ordering pattern:**
```
1. JSON Schema changes (openmetadata-spec/)
2. Run: make generate (regenerate Pydantic models)
3. Java backend changes (openmetadata-service/)
4. Run: mvn spotless:apply && mvn test-compile
5. Python ingestion changes (ingestion/)
6. Run: cd ingestion && make py_format && make py_format_check && make unit_ingestion_dev_env
7. Frontend changes (openmetadata-ui/.../ui/)
8. Run: yarn lint && yarn test
9. Database migrations if needed (bootstrap/sql/)
10. Full verification: mvn test or relevant integration tests
```

### Phase 4: Execute

- Work through the plan task by task
- Mark each task complete as you finish it
- If you hit a blocker, stop and discuss — don't silently deviate from the plan
- After all tasks complete, run the final verification

## Rules

- **Never skip Phase 2.** Even if the approach seems obvious, stating it gets alignment.
- **No placeholder code.** Every step in the plan must describe real, complete changes.
- **Schema-first.** If the feature touches data models, start with JSON Schema changes in `openmetadata-spec/`.
- **User approves before code.** Don't write code until the plan is approved.