# Development Workflow

This document defines the default path from idea to released change.

For branch policy, see [branching.md](branching.md).
For release execution, see [release-process.md](release-process.md).
For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).

## Workflow Overview

```mermaid
flowchart LR
    Idea["Idea or Issue"]
    Clarify["Clarify Scope"]
    Design["Design or Plan"]
    Implement["Implement"]
    Validate["Validate"]
    Review["Review"]
    Merge["Merge"]
    Release["Release"]
    Learn["Review Outcome"]

    Idea --> Clarify
    Clarify --> Design
    Design --> Implement
    Implement --> Validate
    Validate --> Review
    Review --> Merge
    Merge --> Release
    Release --> Learn
```

## 1. Clarify Scope

Before implementation:

- Define the objective.
- Identify users or systems affected.
- Confirm acceptance criteria.
- Identify non-goals.
- Note security, data, migration, and deployment risk.

If the task is ambiguous, resolve ambiguity before writing code.

## 2. Design Or Plan

Use a lightweight plan for most changes.

Create or update an ADR in [DECISIONS.md](DECISIONS.md) when the change affects:

- Architecture style.
- Module boundaries.
- Data ownership.
- Security model.
- Deployment strategy.
- Public contracts.
- Long-term operating cost.

## 3. Implement

Implementation expectations:

- Work in a focused branch unless the project policy says otherwise.
- Read existing code before editing.
- Follow [CONVENTIONS.md](CONVENTIONS.md).
- Keep commits logically grouped.
- Update documentation with behavior, setup, or architecture changes.

## 4. Validate

Use the strongest practical validation for the change:

- Build or type checks.
- Unit tests.
- Integration tests.
- End-to-end tests.
- Manual UI or API checks.
- Documentation link checks.

Record validation evidence in the pull request or final work summary.

## 5. Review

Review should answer:

- Does the change solve the stated problem?
- Is it consistent with [ARCHITECTURE.md](ARCHITECTURE.md)?
- Does it follow [CONVENTIONS.md](CONVENTIONS.md)?
- Are risks and rollback needs clear?
- Is validation sufficient?

## 6. Merge

Before merge:

- Required checks pass.
- Review comments are resolved.
- Branch is up to date according to project policy.
- Release notes or changelog entries are added when relevant.

## 7. Release

Follow [release-process.md](release-process.md).

Release work should include:

- Final readiness check.
- Deployment.
- Smoke test.
- Monitoring.
- Rollback readiness.

## 8. Review Outcome

After meaningful releases or incidents:

- Capture what worked.
- Capture what failed.
- Update checklists, docs, tests, or runbooks.
- Add ADRs for decisions that emerged during delivery.