Work Order Writing Guide

This guide explains how to write Work Orders in Software Factory.

What Are Work Orders?

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.

Writing Work Order Descriptions

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.

Summary

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.

In Scope

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.

Out of Scope

Explicitly list what is excluded or deferred. Clarify boundaries with adjacent work orders. This section prevents scope creep by making exclusions explicit.

Requirements

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.

Blueprints

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}

E2E Acceptance Tests

Describe the end-to-end coverage that validates each applicable acceptance criterion. Keep the specification independent of a particular test package or repository layout so the implementer can place it according to the codebase's current testing conventions.

For each scenario, state the acceptance criterion, preconditions, user actions, observable assertions, and any persistence check. Prefer accessible selectors and user-visible behavior over implementation details.

Format each test specification as follows:

### {Acceptance criterion}: {Scenario name}

**Preconditions:** {Required user, project, and data state}

**Priority:** {P0/P1/P2}

**Expected behavior:** {Description matching the acceptance criterion}

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}

6. Reopen or reload the relevant view and assert the value persisted, when applicable.