Development workflow — backlog traceability, spec freeze, and ADRs
Audience: every engineer and AI agent working on the Ghasi Melmastoon implementation monorepo (
ghasi-melmastoon) and the specification repo (ghasi-e-documentation/ghasi-melmastoon).
Companion: DEFINITION_OF_DONE.md · REQUIREMENTS_GUARD_RAILS.md · ../backlog/IMPLEMENTATION_STATUS.md
1. Assumptions (current programme)
- Specifications are ready and in freeze for the scope we are building: strategic docs, per-service bundles,
docs/07-epics-and-user-stories.md, journeys, and standards are the source of truth for what to build. - Jira (project MEL) is the long-term execution surface; until Jira is the system of record, the documentation backlog is mirrored in ../backlog/IMPLEMENTATION_STATUS.md.
- Code never leads the spec for in-scope features: we do not invent endpoints, events, or behaviours that are not described by an approved work item and the spec corpus it references.
If these assumptions are wrong for a given initiative, stop and re-baseline the programme (roadmap + explicit freeze lift), not a single feature PR.
2. Every change is tied to a backlog work item
| Rule | Detail |
|---|---|
| Required identifier | Every PR must name at least one: user story US-MEL-NNNN and/or Jira MEL-NNN, and the epic EP-MEL-NN when a story is not enough context. Commits in the implementation repo must still include a MEL- reference (see commitlint + CONTRIBUTING.md) — use a work-item ticket for chore (tooling, CI) so nothing is untracked. |
| No orphan implementation | Do not merge features, routes, or domain logic that are only in someone’s head or chat. If it is not in docs/07-epics-and-user-stories.md (or a service bundle / ADR) as part of the agreed scope, the work is out of process. |
| Spikes | Time-boxed R&D is allowed on branch spike/<slug> (see CONTRIBUTING.md) and must produce: findings doc + recommendation; no production behaviour merged from a spike without a story and spec alignment. |
| Status updates | When implementation progresses a story (new AC satisfied, or scope clearly advanced), update ../backlog/IMPLEMENTATION_STATUS.md in the same PR or a sibling doc PR that merges with it. When Jira is live, also transition the MEL issue. |
3. Spec freeze — how to change behaviour
| Situation | Action |
|---|---|
| Implement existing spec | Normal PR: link story, cite spec paths, match contracts. |
| Bug fix (spec was right, code wrong) | PR fixes code; no spec change. |
| Spec error discovered | Do not silently “fix” the product in code. Open an ADR (or the minimal doc fix the ADR points to) and get explicit approval; then code + spec in a coordinated change set. |
| New product decision (new service responsibility, new event, breaking API) | ADR first under docs/architecture/ (see ADR-0001 for style), then service bundle / 07-epics / backlog as needed. |
| Small doc typo | Doc PR, no ADR, if it does not change behaviour. |
ADR process (summary): propose → review → docs/architecture/ADR-NNNN-<slug>.md → link from affected service specs and epics. Versioned APIs and event subjects must stay consistent with NAMING.md and ERROR_CODES.md after the ADR is accepted.
4. What “not inventing” means
- No new public routes, BFF operations, or Pub/Sub subjects without a line in the relevant API_CONTRACTS.md / EVENT_SCHEMAS.md (or the strategic doc that owns them) and a backlog story (or ADR that adds the contract).
- No new
MELMASTOON.*error codes without ERROR_CODES.md in the same change set. - No new ID prefixes or aggregate tags without NAMING.md (or ADR to extend naming).
Refactors, tests, and internal implementation details (private helpers, file layout) are allowed when they do not change observable behaviour; still tie the PR to the story you are hardening (or refactor + ticket).
5. PR and merge expectations
Implementation monorepo CONTRIBUTING and PULL_REQUEST_TEMPLATE require:
- Story / Jira / epic in the description.
- Spec alignment attestation (followed, doc PR, or documented deviation with approval).
- IMPLEMENTATION_STATUS update when story status moves.
- DoR / DoD and security gates as per REQUIREMENTS_GUARD_RAILS.md and DEFINITION_OF_DONE.md.
6. Cross-references
| Doc | Role |
|---|---|
| ../07-epics-and-user-stories.md | Full ACs for all stories |
| ../backlog/IMPLEMENTATION_STATUS.md | Monorepo implementation status (interim) |
| ../backlog/README.md | How to load epics and stories |
| JIRA_PROJECT_SETUP.md | When Jira is active |
ghasi-melmastoon/AGENTS.md | AI agent rules (this workflow is binding there too) |
Document version: 1.0.0
Last updated: 2026-04-23