# 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, bug, or feedback"]
    Clarify["Clarify scope"]
    Plan["Plan or ADR"]
    Implement["Implement"]
    Validate["Validate"]
    Review["Review"]
    Merge["Merge"]
    Release["Release"]
    Learn["Update docs/checklists"]

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

## 1. Clarify Scope

Before implementation:

- restate the objective in engineering terms;
- identify affected public, admin, backend, database, or deployment surfaces;
- confirm acceptance criteria and non-goals;
- identify security, authorization, migration, data-loss, or live-production
  risk;
- ask concise questions when ambiguity affects important behavior.

## 2. Inspect Existing Context

Read the relevant source and docs before editing:

- [PROJECT.md](PROJECT.md) for runtime and product facts;
- [ARCHITECTURE.md](ARCHITECTURE.md) for boundaries;
- [CONVENTIONS.md](CONVENTIONS.md) for coding standards;
- [DECISIONS.md](DECISIONS.md) for durable trade-offs;
- [../DESIGN.md](../DESIGN.md) for UI work;
- feature plans such as [workflow-feedback-plan.md](workflow-feedback-plan.md)
  when the task builds on planned product feedback.

## 3. Plan The Change

Use a lightweight plan for non-trivial changes. Create or update an ADR when
the change affects:

- architecture style or module boundaries;
- data ownership or public contracts;
- authentication, authorization, or security posture;
- deployment strategy, migrations, or long-term operating cost.

## 4. Implement

Implementation expectations:

- keep changes focused and reviewable;
- follow existing frontend/backend patterns;
- split large Vue surfaces into smaller components or composables;
- keep backend/admin data authoritative for public behavior;
- avoid unrelated refactors unless needed for the requested change;
- preserve user changes in a dirty worktree.

## 5. Validate

Default validation:

```bash
cd frontend
npm run build

cd ..
dotnet build Backend/Backend.csproj --configuration Release
git diff --check
```

Add targeted validation by risk:

- API checks for backend behavior;
- authenticated checks for admin/team/permission changes;
- browser checks for visible UI changes;
- responsive geometry checks for layout work;
- database health and migration checks for schema changes;
- live checks only for release or explicitly live-scoped work.

When frontend and backend are both actively used for local verification, keep
them running as a pair or shut both down together.

## 6. Review

Review should answer:

- Does the change solve the stated problem?
- Does it preserve backend/admin truth?
- Is authorization enforced at the trusted boundary?
- Are migrations and deployment risk understood?
- Are docs and validation sufficient for the risk?

## 7. Merge And Release

`main` is the production deployment branch. Pushes to `main` run CI and deploy
when the workflow conditions match. Follow [release-process.md](release-process.md).

## 8. Learn

After meaningful releases, regressions, or repeated review feedback:

- update docs or checklists;
- add or update ADRs;
- add regression coverage when practical;
- record follow-up work where the repo exposes an operational or test gap.