Ops Requirements Guidelines

Ops Requirements Guidelines

Reduce common LLM mistakes when reasoning about operational workflows. Treat a proposed solution as a hypothesis, trace required information to the real work that creates it, and produce the smallest experiment that can resolve the important uncertainties.

Tradeoff: These guidelines favor evidence and explicit uncertainty over a fast, polished solution. Use judgment when the workflow is already known and verified.

1. Understand Before Designing

Do not invent the operation. Find the decisions behind the request.

Before proposing a system:

• Separate the brief into stated facts, inferences, assumptions, and unknowns. Never present one category as another.
• Restate the desired outcome as decisions or actions someone must be able to take. “Track production” is a feature; “know whether tomorrow's orders can ship” is an operational decision.
• Identify the users, decision owners, and people who perform or report the work. Do not treat “the business” as one actor.
• If the brief already names a solution, preserve it as a candidate and challenge the problem-solution fit.
• Surface conflicting statements and plausible alternative interpretations. Ask only questions whose answers could change the requirements, prototype, or architecture.

The test: Could the customer agree with the problem statement before seeing any proposed technology?

2. Follow Every Fact to the Ground

A system knows only what a credible source observed or produced.

For every fact the system needs:

• Name who or what observes the real-world event: a person, transaction, message, document, machine, sensor, clock, or another system.
• Name when and how the fact enters the system, how fresh it must be, and what reporting burden it creates.
• Classify capture as automatic, a by-product of existing work, a new human report, or a human verification. Prefer the least burdensome credible source.
• Record provenance: source, reporter, event time, reporting time, and supporting evidence when useful.
• Name a way to detect missing, late, contradictory, or implausible data. Use reconciliation, independent sources, photos, spot checks, or bounded rules where appropriate.
• Consider incentives. A person may report differently when the same number is used to judge them.

If no credible source exists, label the fact as an open dependency—not a requirement the system can magically satisfy.

The test: For every number or status shown to a decision-maker, can you point to where it was born and how it could be wrong?

3. Represent Operational State Explicitly

Unknown, stale, disputed, and corrected are valid states.

• Distinguish observations and events from the current state derived from them.
• Define the minimum entities, identifiers, statuses, transitions, quantities, and timestamps required by the decisions.
• Preserve the original report and later corrections when auditability matters. Do not silently overwrite conflicting evidence.
• Give each important state a freshness rule and a confidence or verification status when the source is uncertain.
• Keep authoritative state in durable data outside the LLM conversation. Use deterministic rules for totals, transitions, deadlines, and reconciliations when practical.
• Use the LLM where ambiguity is useful: extracting proposed events from messages, requesting clarification, explaining exceptions, and summarizing state. Require validation before an extracted proposal becomes authoritative when the cost of error is material.

The test: Can the system say “I do not know,” explain why, and identify the next action needed to know?

4. Fit the Work and Start Small

Add as little operational burden and technology as the outcome allows.

• Reuse channels and artifacts already produced by the work before introducing a new application, form, sensor, or dashboard.
• Trace every collected field to a decision, control, or required record. If nobody acts differently because of it, question why it is collected.
• Count new actions per role and per shift or day. Treat each action as a cost and a likely point of failure.
• Prefer a manual or message-based trial when it can test the operating mechanism before software is built.
• For a new or changing operation, model only the stable decisions and the next testable process. Do not encode a speculative mature workflow.
• Recommend dashboards, agents, integrations, or sensors only when their benefit and information source are clear.

The test: What is the smallest credible mechanism that lets the team make the target decision?

5. Make the Outcome Testable

Turn desired outcomes and failure modes into observable evidence.

• Define success from the user's perspective: decision time, information freshness, discrepancy detection, reporting burden, or another observable result.
• Mark proposed thresholds as placeholders until the customer agrees to them.
• Test failure cases deliberately: a missing update, a late report, contradictory reports, an incorrect count, a correction, and a temporarily unavailable source.
• Separate what the prototype demonstrates from what remains unproven.
• Treat architecture as a response to validated requirements, not as the first deliverable.

The test: After a short trial, will the team know whether the operating mechanism works and why?

6. Make the Reasoning Visible

Use diagrams to expose dependencies and uncertainty, not to decorate the document.

• Include at least one editable Mermaid flowchart that connects the proposed idea to the desired outcome through the decisions, facts, sources, capture and validation, operational state, actions, and evidence required between them.
• Derive every node and edge from the written analysis. A diagram must not introduce facts, actors, systems, or certainty that the evidence ledger does not support.
• Mark assumptions and unknown dependencies explicitly in node labels. Use dotted edges for unverified or proposed relationships and solid edges only for stated or validated relationships.
• Keep labels short and put detail in the evidence ledger or information-chain table. Split a crowded diagram instead of shrinking it into an unreadable map.
• When state transitions are material, add a Mermaid stateDiagram-v2 showing normal, uncertainty, correction, and failure states.
• When AI or automation is proposed, add a Mermaid architecture boundary showing real-world sources, capture, validation, the authoritative system of record, deterministic rules, AI interpretation or communication, and human decision-makers.
• Keep Mermaid source in the deliverable so the customer can revise it. If the target format cannot render Mermaid, retain the source and provide an equivalent text flow rather than replacing it with an opaque image.

The test: Can a reviewer trace each claimed outcome backward to the action, state, validated information, and real-world source it depends on—and see where that chain is still uncertain?

Required Output

Produce a concise analysis in this order. Adapt the depth to the brief; do not manufacture content to fill every section.

1. Outcome and decisions — Restate the operational outcome and the decisions it must support.

2. Evidence ledger — List stated facts, inferences, assumptions, unknowns, and contradictions separately.

3. Visual breakdown — Add the core Mermaid idea-to-outcome chain. Add state or architecture diagrams when the criteria above apply.

4. Information chain — For each necessary fact, show:

   Decision → fact needed → real-world source → capture method → freshness → validation → response when unavailable
   

5. Operational state — Describe the minimum events, entities, statuses, transitions, provenance, and uncertainty states.

6. Human and automatic work — Separate automatic capture, existing-work by-products, new human reports, and verification.

7. Smallest useful prototype — State what to simulate, what to run with real people, what failure cases to inject, and what evidence to collect.

8. Architecture only as needed — Keep the system of record and deterministic rules separate from LLM interpretation and communication.

9. Priority discovery questions — Ask the questions most likely to change the design first.

10. Not building yet — Name deferred components and the evidence required before adding them.

For a fictional worked example, read references/worked-example.md.