This guide explains how to write Work Orders in Software Factory.
Work orders are implementation tasks that deliver requirements while adhering to the blueprint specifications. Each work order tells a developer what to build, what specifications to follow, and how to verify the work is complete. A well-written work order eliminates ambiguity and prevents scope drift—developers can execute without asking clarifying questions.
A work order description gives a developer everything required to implement the feature without ambiguity or scope drift. It should be precise, implementation-oriented, and free of unnecessary explanation. Every description must include six sections: Summary, In Scope, Out of Scope, Requirements, Blueprints, and E2E Acceptance Tests.
Clearly answer: "What is being built or changed?" State the outcome this work order enables. Focus on value and system impact, not background explanation. Keep it to 2–3 sentences maximum.
Explicitly list the responsibilities owned by this work order. Define functional boundaries. Do not restate acceptance criteria verbatim, and avoid low-level implementation steps. The goal is to make clear what this work order owns.
Explicitly list what is excluded or deferred. Clarify boundaries with adjacent work orders. This section prevents scope creep by making exclusions explicit.
Copy the requirements and acceptance criteria verbatim from the requirements document. Include every requirement and every acceptance criterion that falls within this work order's scope. Use identical formatting and IDs. Do not modify wording. If only a subset applies, include only the applicable acceptance criteria. Do not add interpretation or commentary.
Name the source blueprint(s) that inform implementation. Keep this minimal—the implementer will read the full blueprints directly. List each blueprint with a one-line summary of what it covers:
- {Component Blueprint Name} — {one-line summary of what it covers}
- {Another Component Blueprint Name} — {one-line summary}
Describe the end-to-end test coverage that validates the acceptance criteria. These should be written as structured test specifications that follow the e2e-validator conventions—organized by coverage requirement groups (COV_ IDs that map to REQ- IDs) with individual test cases per acceptance criterion.
Coverage map reference: `e2e-validator/docs/COVERAGE.md` defines the mapping between REQ/AC IDs and COV/@COV IDs, plus tag taxonomy and priority rules.
For each requirement group, describe the `test.describe` block name and coverage ID, individual test cases with @COV_ tags, test names, and step-level descriptions, specific element selectors, user actions (click, type, press), and assertions, data preconditions (e.g., "Given a work order with status 'Backlog'"), and persistence verification patterns (close panel, reopen, assert value persisted).
Format each test specification as follows:
```
### COV_{PREFIX}_{NNN}: {Requirement Group Name}
**File:** `e2e-validator/tests/{module}/{area}/{spec-file-name}.spec.ts`
**Tags:** {Tag(s) from coverage taxonomy} | **Priority:** {P0/P1/P2}
**@COV_{PREFIX}_{NNN}.1 — should {description matching the AC}**
1. Sign in and navigate to {module}
2. {User action — e.g., open a work order from the table}
3. Assert {expected visible result}
4. {Next action}
5. Assert {state change or persistence}
**@COV_{PREFIX}_{NNN}.2 — should {next AC description}**
1. ...
```