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.