Work Order Writing Guide

This guide explains how to write Work Orders in 8090 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 where its boundaries are. A well-written work order removes ambiguity and prevents scope drift, so 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. The default description template has five sections: Summary, In Scope, Out of Scope, Related Requirements, and Relevant Blueprint References. The Agent follows the same template when it creates work orders.

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 two or three sentences.

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.

Related Requirements

Copy the applicable requirements verbatim from the requirements document, including their user stories and the relevant acceptance criteria. 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.

Relevant Blueprint References

Cite each blueprint that informs the implementation by its exact document name, and list the specific sections that apply to this work order. Give a one- or two-sentence summary of what each cited section governs. Keep this minimal: the implementer reads the full blueprints directly, so do not restate technical details or introduce new architectural decisions.

- `{Blueprint name}`, `{Section name}`: {One or two sentences on what the section governs}
- `{Another blueprint name}`, `{Section name}`: {One or two sentences}

Adding E2E Acceptance Tests

The default template has no end-to-end (E2E) test section. If your team wants every work order to specify its E2E coverage, add an E2E Acceptance Tests section to the Description Guidelines in your project's Work Orders Writing Rules skill, in Skills. The Agent follows that skill whenever it creates or edits work orders.

A useful E2E section describes 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, for example: 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.