Work Orders: Robust & Repeatable AI Workflows

Background

To ensure high-quality, sustainable, and well-thought-out contributions, we use a “Work Order” process. This process is designed to guide AI-assisted development through a structured workflow, preventing premature code generation and encouraging a more thorough design and planning phase.

The work order concept addresses several challenges:

  • Promotes Deeper Thinking: It pushes the AI model to analyze the task more deeply before implementation.
  • Enables Collaboration and Persistence: Work orders, being stored in source control, allow for partially completed efforts to be shared, reviewed, and resumed later, even across different sessions.
  • Reduces Errors: By following a structured process, we can avoid common pitfalls like non-working code, unsustainable designs, and incomplete features.

What is a Work Order?

A “work order” is a formal process for accomplishing a common development task repeatably using AI tooling. It follows a micro-waterfall model where the AI and the user collaborate on a plan, which is documented in source-controlled markdown files. Once the plan is agreed upon, the AI proceeds with the implementation.

Each work order is defined by two files in the docs/work_order directory:

  • docs/work_order/<work_order_name>.md: The main workflow definition. This file is only loaded into the context when the work order is active.
  • docs/work_order/<work_order_name>_trigger.md: A concise file containing a short description and the trigger conditions for the AI to suggest the work order. This file is always included in the context.

Example Work Order Types

  • new_feature: Add a new feature, from product requirements to implementation.
  • compile_docs_examples: Convert inline documentation code examples into standalone, buildable, and testable files.
  • test_enhancement_audit: Audit and improve the test coverage for a specific area of functionality.
  • (Others to be proposed)

Work Order Execution

The execution of a work order is divided into distinct phases. The AI should explicitly ask for user confirmation before moving from one phase to the next.

The “Flush” Operation

A key part of the work order process is the “Flush” operation. A flush is the process of pushing all relevant context from the conversation—including new requirements, design decisions, files read, and files modified—into the scaffolding documents.

A flush must be performed at the end of each phase. This ensures that the scaffolding files are always up-to-date and accurately reflect the current state of the work. The AI must ask for user approval before flushing and moving to the next phase.

Work Order Phases

  1. Setup: Create the scaffolding documents relevant to the work order type. The specific work order definition outlines the required files, their initial content, and their location.

  2. Planning: Iteratively expand the scaffolding documents. This involves reading existing code, asking clarifying questions, and refining the plan with the user. A key output of this phase is an initial estimate of the work's scope and size.

  3. Critic: Before implementation, critically review the plan. This phase is conducted in two stages to ensure a thorough and deep analysis.

    • Stage 1: Initial Review: Act as an expert principal software engineer. Scrutinize the proposed changes, read the surrounding code, and look for potential issues. Consider maintainability, fragility, and interactions with other parts of the system. The goal is to catch lazy planning, such as assuming what code does instead of reading it.
    • Stage 2: Deep Expert Review: Based on the findings from the initial review, conduct a second, more intensive critique. Challenge every assumption. The perspective is that of a skeptical, external auditor poking holes in the approach. The Critic must actively challenge the plan's assumptions. Use tools like read_file and glob to find and examine existing patterns and prove the plan is viable before writing code. The goal is to find flaws in the plan before they become bugs in the implementation.

  4. Implementation: Work through the defined tasks incrementally. The scaffolding documents should be updated as milestones are reached and understanding evolves. The Implementation phase must proceed as a series of small, verifiable steps. For each task, the required workflow is: 1. Implement the minimal change. 2. Verify the change by running the appropriate build or test command. 3. Document the successful step by checking off the task. Do not proceed to the next task until the current one is verified.

  5. Verification: Evaluate whether the goal has been accomplished. This includes ensuring the implemented code matches the design, all tasks are completed, and any implied testing has been performed.

  6. Work order review (Optional): After completing the work, consider reviewing the work order process itself. This is an opportunity to reflect on what went well and what could be improved in the work order template (e.g., the new_feature.md skeleton). The goal is to refine the process for future tasks. This review should also be a two-stage process:

    • Stage 1: Initial Feedback: Discuss with the user if any improvements can be made to the work order template for future use.
    • Stage 2: Deep Analysis: Based on the initial feedback, perform a deeper analysis of the work order's execution. Identify specific, actionable improvements to the process or templates and propose them to the user.

  7. Integration & Cleanup: The work is not done when the code is committed. This final phase ensures the change is properly integrated, documented, and communicated. Only after these steps are complete is the work order finished.

Learning from Experience: Capturing Blind Alleys

To avoid getting stuck in failure loops, it is critical to document blind alleys and failed approaches. When an attempted change (e.g., Change A) fails and you move to another approach (Change B), the reasons for Change A's failure must be recorded. This prevents re-trying failed solutions.

Each work order's design document (e.g., design.md) should have a section for “Alternatives Considered” or a similar title. This section must be updated with:

  • A description of the failed approach.
  • A clear explanation of why it failed.
  • Any insights gained from the attempt.

This practice ensures that the project benefits from all work, even failed attempts, and provides valuable context for future development and for resuming work.

Work Order State

The current state of a work order is defined entirely by the content of its scaffolding files in git. In a Gerrit-based workflow, a single commit is typically amended over time with updates to these files, representing the evolving state of the work order.

Pausing and Resuming Work

A key benefit of the work order system is the ability to pause and resume work without losing context. To resume a work order, the AI must first re-read the design.md (or equivalent) and tasks.md in their entirety to fully reload the context before proceeding.

Common Work Order Processes

Every work order must include a task list in a markdown file (e.g., tasks.md). This file must indicate the current phase of the work order.

Here is a typical structure for a tasks file:

**Work order:** new_feature: New filtering syntax

- [x] **Setup:** Scaffolding documents created.
- [x] **Planning:** Iterating on design and task list.
- [ ] **Critic:** Not started.
- [ ] **Implementation:** In progress.
- [ ] **Verification:** Not started.
- [ ] **Work order review (Optional):** Not started.
- [ ] **Integration & Cleanup:** Not started.

---

### Detailed Tasks

... (work-order-specific task hierarchy) ...

The named work order type (e.g., “new_feature”) should correspond to a defined work order.

Initiating and Continuing Work Orders

The AI should proactively suggest using a work order when a user's request is complex and would benefit from a more structured approach. Each work order has a series of hints (triggers) for when to suggest it.

When initiating a work order seems appropriate, don't just suggest starting the work order, also give a two-sentence summary of that work order.

Standardized AI Communication

To make the work order process clear and predictable, the AI assistant will use standardized phrases at key points in the workflow. This allows users to easily recognize the state of the process.

  • Suggesting a work order:

    This seems like a good opportunity to use a work order. Would you like to start the Work Order: [Work Order Name]?

  • Moving to a new phase:

    The [Current Phase Name] phase is complete. I will now perform a flush to update the scaffolding documents. Once that is done, are you ready to move to the [Next Phase Name] phase?

  • Completing a work order:

    The Work Order: [Work Order Name] is complete. I will now delete the scaffolding files and prepare the final commit.