The spec agrees on behavior, the prompt gives the AI a task, and the Scorecard checks impact. A lightweight work card is enough for small tasks.
A spec is the versioned source agreement for the intended behavior of a change. It connects rules, examples, failure cases, and acceptance criteria. Code, tests, and documentation refer to the same version.
For a bug, the existing spec may only need a reproduction, expected behavior, and a regression test. Larger or riskier changes need more clarification.
“Build a login page” leaves many decisions open. A spec names the endpoint, inputs, error responses and specific success cases. AI results are then checked against these requirements.
Integer quantities; quantity 0 removes the item; do not exceed stock; money in cents; shipping costs 490 cents, free from 5,000 cents. Removing the last item sets the total to 0 and disables checkout.
Example: PUT /cart/items/{productId} with quantity; 200 on success, 400 for an invalid quantity, 404 for an unknown item and 409 for insufficient stock. In a real shop, prices and access are checked on the server.
People and AI agents must be able to identify the valid version. Otherwise code, tests, and acceptance use different foundations. A traceable history shows what changed, why, and who confirmed it. It supports debugging, impact analysis, and rollback.
For a bug: If the agreed behavior is unchanged, reference the existing spec and add a regression test. A new business agreement is needed only when expected behavior changes.
View versioning in the shopping cart example · Complete CART 1.0 spec · Fill in the guided specification template
Start as Product Owner with the first five points. Describe the problem and two or three concrete situations in everyday language. The team adds technical details; the Measurement Partner helps with impact measurement.
You do not have to solve technical fields alone. “Open – team to clarify by …” is more useful than an invented answer. Small tasks can stay brief.
This is the completed example spec CART 1.0
The guided specification template includes an optional section for criticality, monitoring, alert triggers, SLO / expected availability, failure behaviour and dashboard / tool. SLO and tool references are needed only where relevant.
The more critical a change, the more precise the details. Potential harm, usage frequency, dependencies and recoverability determine the depth. For non-critical changes, a very small entry or none may suffice.
For critical components, monitoring, useful alerts and testable failure behaviour are implemented and evidenced before completion. Consider operations in the Build Loop
SPEC [short name / ID] · Version [0.1] · Status: Draft START HERE AS PRODUCT OWNER Replace the brackets with short sentences. Bullet points are enough. Keep anything unknown as “open” with a named owner. Add technical and measurement details together. Examples are guidance, not requirements. 1. Which problem are we solving, and for whom? The task comes from [team / board / executive team / strategic initiative / other source]. It contributes to [higher-level goal and task link]. Fixed constraints are [goal, date, budget, or mandatory scope]. The Product Owner and team may decide [decision space]. Changes beyond it are confirmed by [responsible person / decision body]. As [target group], I want to [complete a task], so that [benefit]. Today, [observable problem] occurs. This is supported by [feedback, observation, or data; otherwise: still to verify]. Example: customers want to correct their selection so they order the right quantity. Quantity changes are currently cumbersome. 2. What should improve? By enabling [small change], expect [observable improvement] because [assumption]. Value is indicated when [signal or metric] changes from [baseline / still open] to [target / to agree together]. [Unwanted side effect] must not increase. Example: more customers reach checkout, while price errors must not increase. Agree on measurement details with the Measurement Partner. 3. What is the smallest useful scope? This change enables [a few specific capabilities at most]. Deliberately defer [requests outside the scope]. Slice: can the spec be understood with bounded context, implemented without a large system explanation, and verified independently? If not: [smaller specs with their own tests and required context]. The Product Owner and team confirm the split. Invest at most [team effort] and [AI budget]. At [review point], decide whether to continue or shape the scope. Agree on this boundary with [team / responsible person]. 4. Show the intended behavior through examples. AK-01: Given [starting state], when [action], then [visible, testable result]. AK-02: Given [boundary case], when [action], then [expected response]. AK-03: Given [failure case], when [invalid action], then [feedback and unchanged state]. After [further action], [new state] must be visible. Example: given an item with quantity 1, when it is added again, then one line item with quantity 2 is shown. Check: what happens when empty, at 0, above limits, without permission, or after repeated clicks? Include only relevant cases. Do not renumber acceptance-criteria IDs later. 5. What still needs a decision? Open question: [question]. [Name] resolves it by [date]. It blocks [affected implementation / nothing]. Business confirmation by: [Product Owner / Feature Partner, date]. Until then, this spec remains a draft. ADD WITH THE TEAM 6. Technical agreement—the team leads; the Product Owner clarifies business effects. Affected interface / inputs: [contract or link]. Results, errors, permissions, and privacy: [rules / open decisions]. Tests: [acceptance-criteria IDs, counterexamples, integration and regression tests]. Business acceptance: [person, scenarios, test version, and date / trigger]. Release, operational checks, and rollback: [plan, owner, and triggers]. For small tasks, a reference to existing standards may be enough. Reliability & Observability · OPTIONAL Fill in only relevant details. Low-risk changes need little or no additional information; a reference to applicable standards may be sufficient. Scale depth to criticality, potential harm, frequency of use, dependencies, and recoverability. Criticality: [high / medium / low] Monitoring: [Which metrics, logs, or traces are required?] Alert when: [Which specific deviation triggers an alert? Clarify response, ownership, and escalation.] SLO / expected availability: [optional, only when relevant to the component] Failure behavior: [retry, fallback, rollback, degradation, manual intervention, or another response] Dashboard / tool: [optional link to Datadog, Grafana, Sentry, or another system] Accountable people confirm criticality, acceptable risk, alert thresholds, SLOs, escalation, and approval. 7. Evaluate impact—with support from the Measurement Partner. Primary metric / numerator / denominator: [definition]. Source / events / comparison / period: [plan]. Guardrail metrics and decision rule: [limits, outstanding data]. Scorecard: [link]. [Person] decides continuation at [review point]. 8. Record a reliable version. Owner: [name]. Versioned source spec: [link]. Confirmed version and immutable source: [version + commit link / document revision]. AI tasks, tests, review, and acceptance reference [this version]. The release connects [spec version, verified code version, and evidence]. Change history: [version, date, change, rationale, affected acceptance-criteria IDs, confirmation]. When changes occur, check effects on ongoing AI tasks and explicitly record the agreed version. QUICK CHECK BEFORE IMPLEMENTATION Can another person use these examples to tell what correct behavior is? Are scope, accountability, and investment boundaries clear? Are critical open questions resolved and rules confirmed by people? Is everyone using the same spec version?
All components in one place: brief, benefit, scope, rules, technical contract, tests, measurement, release and versioning. Open questions for a real implementation are explicitly identified.
SPEC CART · Version 1.0 · Reference version of the LoopsWork learning example This completed example spec describes the shopping cart rules already shown. Roles, budget, and measurement plan are illustrative assumptions. It is not a real product approval or evidence of a production implementation. Reference source: https://loopswork.dev/en/docs/#cart-spec Owner: Online Shop Product Owner (example role). Business confirmation: Feature Partner and Product Owner; technical agreement: Delivery Team; measurement plan: Measurement Partner. In this learning workflow, CART 1.0 is confirmed once B3 is complete. Add a real confirmation date and immutable Git commit or document revision when adopting it into a project. The website URL alone does not replace that fixed version.
Illustrative task: a department leader owns the strategic initiative “Simplify shopping” and commissions the Product Owner to deliver the cart contribution. This is an additional example assumption. The Product Owner prioritizes scope within the mandate; the team chooses implementation and division of work. Changes to the higher-level goal or budget go to the department leader. Customers with selected items should be able to correct quantities, remove items, and understand the total price before checkout. The example assumes that cumbersome corrections and unclear shipping costs make checkout harder to start. This learning demo has no real user evidence; in a project, the Feature Partner checks the assumption through user tests and feedback.
Hypothesis: if customers can easily change quantities and understand the total price, more eligible sessions with a filled cart will start checkout. Example baseline: 58%. Example target: at least 62% while meeting guardrails. These figures are fictional assumptions, not measurements from this website. For the first change: at most five team working days and €50 in AI costs. Review at half the budget spent. Team effort is not calendar duration. In this example, the Product Owner may continue, shape scope, or stop within this boundary. The responsible department leader confirms a larger budget or changed strategic goal.
Included: add items, change quantities, remove line items, calculate basket value and shipping costs, display the total, and prevent checkout from an empty cart. Excluded: discount codes, wishlist, guest-account synchronization, payment, and real order processing. This website runs the rules locally in the browser. A production cart also needs server-side checks, access control, operations, and approvals. Requirements for a real service below are not existing website features.
AK-01 · Add: an existing item does not create a second line item. Given coffee with quantity 1, when the same item is added again, then one line item has quantity 2. AK-02 · Quantities: only nonnegative whole numbers are valid. Quantity 0 removes the line item. Reject negative and fractional quantities and keep the existing cart unchanged. AK-03 · Stock: the requested quantity must not exceed available stock. With stock 5, reject quantity 6 without changing the cart. Quantity 5 is valid. AK-04 · Money and totals: calculate money in whole cents. Basket value is the sum of quantity × valid unit price. Total price is basket value plus shipping. Update displayed totals after every successful add, change, or removal. Server-side prices are authoritative in a real service. Example: 2 × 1,490 cents + 490 cents shipping = 3,470 cents. AK-05 · Shipping: for a nonempty cart below 5,000 cents basket value, shipping costs 490 cents. At exactly 5,000 cents or above, shipping is 0. Boundary cases: 4,999 → 490 cents shipping; 5,000 → 0. After a quantity change crosses the threshold, apply the new total immediately. AK-06 · Empty state: after the final item is removed, basket value, shipping, and total are 0. Checkout is disabled and the empty state is clearly explained. Invalid actions show understandable feedback and leave both items and totals unchanged. Stock limits also apply to repeated additions.
Draft: PUT /cart/items/{productId} Body: { "quantity": 2 } sets the requested absolute quantity. quantity: 0 removes the line item. Repeating the same set operation does not increase quantity again. The add action in the UI determines the new target quantity. 200: updated cart including server-side totals. 400: invalid quantity. 404: unknown item. 409: insufficient stock. These errors leave the cart unchanged. The service validates inputs, current price, stock, and permission for the affected cart. This contract does not place an order or reserve stock. Before production implementation, the team agrees on authentication, 401/403 handling, concurrent changes, transaction boundaries, and the exact response schema. These open technical issues are not implicit freedom for agents. They block the affected production work.
Tests reference CART 1.0 and the relevant acceptance-criteria IDs. The Reviewer uses the same fixed spec version as the implementing agent. Automate checks for repeated additions, quantity 0, negative and fractional quantities, stock exactly reached and exceeded, cent calculations, both sides of the shipping threshold, and empty checkout. Check state transitions: after every action, line items, basket value, shipping, and total must agree. For a real implementation, also test interface errors, unauthorized access, current server-side prices, and concurrent changes according to the confirmed contract. The Delivery Team provides evidence and a human reviewer checks independently. The Feature Partner accepts real shopping flows: changing quantities, removing the final item, exceeding stock, and crossing the shipping threshold. Record spec version, code version, test cases, and gaps. Silence is not acceptance. Executable website test cases are learning aids. They do not replace server integration, security review, or business acceptance.
Primary metric: eligible sessions starting checkout divided by eligible sessions with a filled cart. Exclude test traffic and count repeated events only once per session. Measurement points: successful quantity changes, cart errors, and checkout starts. Attribute actions clearly; do not collect free-text personal data. Example measurement window: days 6–18 after activation on day 5, comparing a control group with the new version. The 1,000 sessions per group are illustrative. The Measurement Partner agrees on group assignment, comparability, and required data volume in advance. Example guardrails: change errors at most 1%; loading time p95 at most 1.5 seconds. Also observe price complaints and completed purchases; agree on their decision thresholds before a real experiment. On day 20, the Product Owner reviews the Scorecard with the team and partners, decides within delegated authority, and returns findings to the commissioning department leader. The leader decides strategic changes. Missing data or unresolved comparability leads to further investigation rather than automatic expansion. Address urgent harmful findings immediately. The Scorecard with fictional results is at https://loopswork.dev/en/docs/#scorecard. This website does not collect these shop metrics.
In the example, activate for a limited user group after business acceptance on day 5, and only with the required approvals. The release links CART 1.0, actual code version, test evidence, acceptance, and Scorecard. Assign measurement data to the release and user group. The team and release approver check error rate, price accuracy, and data collection. Stop activation and use the agreed rollback path for incorrect prices or harmful findings. Before a real release, clarify and test the switching mechanism, accountable person, and handling of data already changed. After rollback, code, configuration, and the associated spec version must match.
Open before real implementation: user evidence (Feature Partner), authentication and concurrent access (team), comparison design and guardrails (Measurement Partner), approval and rollback paths (team and release approver). Resolve each before implementation or the affected work starts; assign real names and dates in the project. Version 1.0 documents the six rules already agreed in the learning example. This completed version brings them together and explains their use; it does not change the shipping threshold. AI tasks, tests, review, and acceptance cite CART 1.0 and a fixed commit or document revision. Review a business change as a new draft with differences, rationale, affected acceptance-criteria IDs, and human confirmation. Check effects on ongoing tasks. The CART 1.1 proposal with a 6,000-cent shipping threshold described on the example page is hypothetical and not part of this version. CART 1.0 with 5,000 cents remains valid until a new agreement is explicitly confirmed.
Create your own spec with the guided specification template · Explore the rules in the Shopping Cart Example
Small Specs need Small PRs too. A cohesive change with a spec reference and evidence is easier to review than a large catch-all PR.
PR review & merge approval: workflow, accountability and scope →
The template includes the short checklist. Conditional items may be marked “not relevant” with a brief reason. Missing evidence and blocking findings remain visible.
PR · [Short title] Purpose & Small Spec: [Why? Link to the current spec version] Change & boundaries: [What changes? What is explicitly out of scope?] Risk & affected areas: [Possible impact, interfaces, data, permissions] Evidence: [Tests/checks performed + results + links; agent-review findings/version; name checks not performed] Known limitations & open points: [Finding, blocker, owner; or none known] Operations & rollback (if relevant): [Monitoring, alerts, rollback and recovery; otherwise not relevant + reason] Review & merge approval: [Named human reviewer in the Delivery Team; reviewed commit/version, decision and date] REVIEW CHECKLIST Conditional items may be marked “not relevant” with a brief reason. - [ ] Spec & scope: Does the change meet the spec and stay within the agreed scope? - [ ] Clarity & architecture: Are the change’s structure, maintainability and architecture sound? - [ ] Security & data access: Are security, data access and permissions adequately protected? [checked / not relevant + reason] - [ ] Tests & failure cases: Are tests and checks meaningful, including relevant failure cases? - [ ] Interfaces & existing functionality: Have effects on interfaces and existing functionality been checked? [checked / not relevant + reason] - [ ] Operations & rollback: Where operations are affected: are monitoring, alerting, rollback and recovery defined and supported by evidence? [checked / not relevant + reason] - [ ] Blocking findings resolved and rechecked; relevant changes after approval resubmitted for review.
The Feature Scorecard is a compact decision sheet for a feature or value goal. It brings together expected impact, the measurement plan, results and the resulting product decision. It assesses a change's impact, not individual performance.
In V1 and V2, agree on the hypothesis, baseline, target, primary metric, guardrail metrics, data sources, and comparison. Include measurement events in B3.
From B10/V3: identify the version and user group, check collection and add results. The Measurement Partner checks data quality and uncertainty.
In V4–V6 and the Value Review: PO, team and partners assess benefit and side effects. Record the decision, owner and next checkpoint.
All values and targets below are fictional example assumptions. This site collects no shop data.
| Field | Entry |
|---|---|
| Reference & accountability | Spec CART 1.0 · Activation on day 5 · PO decides within delegated authority; Measurement Partner checks data. |
| Hypothesis | If customers can easily change quantities and understand the total price, more eligible sessions with a filled cart will start checkout. |
| Primary metric | Eligible sessions starting checkout ÷ eligible sessions with a filled cart. Exclude test traffic; count repeated events within a session only once. |
| Baseline & target | Comparison value 58%. Example target: at least 62% within guardrail limits. Check baseline and comparability before implementation. |
| Measurement plan | Days 6–18: concurrent comparison group and new variant, each with 1,000 eligible sessions for an illustrative analysis. Measurement Partner verifies grouping, assignment and required data volume in advance; 1,000 is not a general minimum. |
| Outcome | Comparison: 580/1,000 = 58%. Variant: 640/1,000 = 64%. Difference: +6 percentage points. This is not yet evidence of additional purchases or a causal effect. |
| Guardrail metrics | Change errors: example 0.6%, limit ≤ 1%. p95 load time: 1.2 s, limit ≤ 1.5 s. Add price complaints and completed purchases; these are still missing here. |
| Uncertainty | Randomisation is unverified; user groups could differ. Revenue and complaint findings are missing. Numbers alone are insufficient to justify expansion. |
| Decision on day 20 | PO: retain the bounded variant, do not expand yet. Measurement Partner clarifies the comparison and missing findings; team adds necessary measurement points; next checkpoint in 5 working days. |
Update scorecards before the ritual. Missing data leads to an investigation brief with an owner and deadline. Address urgent failures or harmful side effects immediately; they do not wait for the review.
View timeline and participantsFEATURE SCORECARD [ID] · Version [x] · Updated [date] Feature / Spec / Release: [links and versions] Product decision within the mandate: [PO] · Higher-level decision / requester: [person or body] · Data quality: [Measurement Partner] Problem / target group: [what should improve, and for whom?] Hypothesis: If [change], then [impact], because [assumption]. Primary metric: [definition including numerator, denominator, exclusions] Baseline / source / period: [value or missing + clarification plan] Target and decision rule: [agree in advance] Guardrail metrics: [limits for errors, speed, complaints; relevant error rate, latency, availability or SLO breaches only where they affect users, business impact or reliability] Measurement plan: [events, comparison, groups, data volume, period] Result / user feedback: [values, evidence, data quality] Uncertainty / alternative explanations: [state openly] Decision + reason: [retain/change/expand/investigate/roll back] Next action / owner / review date: [specific] Value Review: regularly every 4 weeks; address urgent findings immediately.
A work card contains just enough clarity to safely complete a bounded task. No separate feature pitch or new scorecard for every correction: a bug fix restores and checks existing expected behaviour.
View the operational workflow · Bug fix on day 8 in the Gantt example
OPERATIONAL WORK CARD [ID] Type: [bug fix / small task / support / incident] Actual / expected / reproduction: [specific case or minimum rule] Impact / urgency / priority: [reason] Responsible: [team member] · Business feedback: [name] Time / AI budget / WIP: [limits, paused work if applicable] Affected spec / rule: [link; extend if needed] Test case / regression: [failing before, passing afterwards] AI brief: [permitted files/tools, AI skill version, AI context] Review / acceptance / rollback: [evidence appropriate to risk] Operational check / completion: [expected state restored?] Reliability & Observability (optional): [monitoring, alert triggers and failure behaviour for critical changes; otherwise brief or omit] Recurring pattern for Learning: [evidence, no new mandatory ceremony]
A recurring finding becomes a bounded trial. Collaboration, waiting times and working conditions belong here, as do AI skills and AI context selection. Each trial investigates one change.
AI skills and AI context explained · Prompt for the Learning Guide
LEARNING EXPERIMENT [ID] Observation and evidence: [rework, waiting time, feedback] Cause hypothesis: [assumption, alternative explanations] One change: [working method OR AI skill OR AI context] Owner / budget / comparison cases: [specific] Expected benefit / counterindicators: [agree in advance] Result: [quality, rework, review time, AI costs, uncertainty] Decision: [retain/adapt/discard] Adoption: [version, rollback path, next review date]
Go directly to the existing overviews and working documents.
B1–B10, V1–V6, and L1–L6 with evidence and feedback.
PRINCIPLESThe existing principles with explanations and examples.
RESPONSIBILITYTasks, decisions, boundaries, and examples.
DAILY WORKA compact template for bugs, support, and small tasks.
LEARNINGTry one change and evaluate the evidence.
CONTEXTFramework proposal, technical sources, and limits of the examples.
Downloads and copy buttons use the same source.
GitHub · Questions & suggestions
Templates and prompts: CC BY 4.0 · Christian Stiller / LoopsWork. Give credit, link the license, and indicate changes. License text ↓
spec.md · pr.md · scorecard.md · cart.md · operation.md · experiment.md