template/docs/workflow.md

Development Workflow

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

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

Workflow Overview

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 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.
• 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?
• Does it follow 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 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.