Spec-driven development: an invoice export walkthrough

Finance needs a file for reconciliation. Its contents must have a meaning when invoices change during assembly, and its download boundary must respond when account access is revoked. The direct-link investigation below follows the latter problem into a design failure and a product decision.

This is a hypothetical investigation, followed by two independent alternative cases. Its clauses and observations illustrate reasoning; no invoice-export experiment or production acceptance is claimed.

Follow the export through a changed decision

Find the decisions hidden in the request

Before designing an exporter, confirm that a file rather than a report view serves the reconciliation workflow. Even after that choice, “matching the requested filters” leaves a consequential question: should membership and values reflect request time, processing time or download time? An invoice updated halfway through assembly makes the choice visible. So does an administrator losing account access after the file has been prepared.

Discussing those cases also selects the size limit to investigate and defers scheduling, notifications and large-export support. One feasibility question remains: can the existing data-access path provide a consistent snapshot at the selected size? Developing examples together to settle the behaviour is BDD discovery. Benchmarking the access path tests whether the mechanism can satisfy the desired rule.

Assume that domain discussion selects these rules for investigation:

• EXP-01: A permitted administrator may request an export for one account and an explicit filter.
• EXP-02: Membership and values reflect one logical snapshot established when the request is accepted.
• EXP-03: Up to 10,000 matching invoices are supported. A larger selection is rejected without making a partial file available.
• EXP-04: Only a complete result becomes downloadable. Exporting does not change invoice state.
• EXP-05: Each new download request requires current authorisation for the account, including requests through direct storage URLs if the design uses them.

These are selected clauses for an investigation, not a declaration that the feature is ready to release. Retry and retention behaviour remain undecided. They are required before exposing a retained-export API, while the snapshot and access boundaries can still be investigated without pretending that the entire capability is ready to build.

These target acceptance examples state the outcomes selected for investigation before the checks are written:

Scroll horizontally to see all columns.

The last row has a maintained acceptance scenario in Part 3’s BDD and acceptance evidence article. A queue, object store, helper function or database layout remains a design choice.

Assign an investigation the agent can actually perform

Suppose the team assigns a two-hour prototype to investigate snapshot consistency and download authorisation. Its deliverable is a record of observations, blockers and a recommendation. Temporary fixtures and output formats are experimental choices; they create no external API commitment. Delivering a retained-export API remains outside the assignment.

The agent needs the clauses, the existing snapshot access path, the account-authorisation boundary and the available integration checks. In a brief read-back, it identifies EXP-02 and EXP-05 and locates the mechanisms for changing an invoice and revoking access in the test environment. If it cannot reach those mechanisms, the team must provide access or narrow the assignment. A fake that always denies access demonstrates only that the fake denies access.

Build one path from an authorised request to a complete temporary file, including denial and failure behaviour. Where needed, compare synchronous and background processing against the same rules. The investigation must exercise both the snapshot and authorisation boundaries to assess whether their guarantees can be achieved together.

For EXP-05, establish revoked access through the relevant permission mechanism, request the actual download boundary and check that no protected data is returned. Smaller internal behaviour can be developed through TDD inside this acceptance check, but its expected results need an independent basis. Use an agreed export fixture rather than calculating the expected result by calling the production export query again.

Separate a broken mechanism from a missing decision

Suppose the initial design returns a long-lived direct object-store URL. A former administrator can still use it after revocation. Checking access only when creating the link plainly fails EXP-05 for later requests. The mechanism must change unless the commitment is explicitly reconsidered through Part 4’s disagreement and contract-correction process. That process distinguishes a code defect from a deliberate change in the obligation; weakening a check until it passes does not make the original rule wrong.

There is a separate unanswered question: what happens if access changes after an authorised download has started? Correcting the direct-link mechanism does not supply that domain decision. Assume the product decision is authorisation at the start of each download request, so an already authorised transfer may finish. The revised requirement can use the EARS form introduced in Part 2:

EXP-05, revised: If a requester lacks current authorisation for the export’s account at the start of a new download request through any download entry point, then the download service shall deny the request without returning invoice data.

This includes requests through direct storage URLs if the design uses them. Retain the denied-download scenario and add a separate scenario for revocation during an active transfer: the transfer may complete or be interrupted, but any new request must be denied.

Requiring immediate interruption would impose a stronger promise and stronger demands on the design and its feasibility evidence. Either choice needs an explicit decision. A mediated download is one possible design, but introducing a proxy does not establish the freshness or failure behaviour of its permission boundary.

Report what the investigation established

The investigation record separates the design failure from the limits of its checks:

Scroll horizontally to see all columns.

Attach each finding to the code state and configuration actually assessed. The responsible person can accept the investigation’s findings while deferring feature acceptance: there is a demonstrated violation and a case the checks never exercised. The next work is to correct the access mechanism, examine the missing snapshot case and resolve the remaining delivery obligations. None of that makes the prototype acceptable for release.

For the snapshot follow-up, coordinate the relevant reads and mutations instead of hoping that their timing overlaps. One possible check pauses assembly after request acceptance and before subsequent reads, commits changes to a selected invoice’s value and to which invoices match, then resumes assembly and compares the result with the agreed pre-change snapshot. Instrumentation must reach the actual data boundary, and the record should include the interleaving exercised. This gives repeatable evidence for that case; it does not establish every concurrent execution.

Alternative: a spec that was wrong from the outset

In this alternative, the initial specification requires an authorisation check at export creation and says nothing about later downloads. Code and scenarios can satisfy those clauses while allowing a former administrator to start a new download.

Suppose a review uncovers an account-access policy that already applied when the specification was approved: revocation must prevent new downloads. The original specification omitted an existing obligation. Its defect was present before implementation began, even if every scenario derived from it passes.

Preserve the policy evidence, correct the rule, add the revocation example and change any implementation that conflicts with the corrected contract. Code that already performs the stronger check may survive unchanged. If the policy had been newly adopted, the diagnosis would instead be a changed requirement with transition obligations. The record should preserve why the earlier decision was valid in that case.

Alternative: the export fails reconciliation

This alternative concerns suitability for the task. The proposed file contains invoice dates and amounts, and finance tries a sample against its existing reconciliation records. Two invoices share those values, so the user cannot tell which record to reconcile because the required reference is absent. The sample satisfies every proposed column rule while failing the task that motivated it.

Keep that observation and revisit the output decision with finance. Assume the domain review establishes which existing reference identifies the record. Add it to the output requirement and retain the ambiguous pair as an acceptance example. Have finance repeat the reconciliation using the revised sample before committing to the representation. This corrects an overlooked need in the existing workflow; it supplies no evidence about production snapshot or access behaviour.

Resolve the remaining questions before release

Keep these three cases as separate records. Do not combine their findings or infer that proposed corrections were verified. An eventual delivery must retain the findings, revised rules, reasons, affected scenarios and actual verification results, and revisit unfinished tasks that depended on the earlier interpretation.

A delivery assignment still needs answers about retry and retention behaviour, file representation and applicable operational bounds. Resolve the questions blocking that work, then review the revised contract and the agent’s assignment. Release requires reviewing the implementation and evidence against those obligations. If a later accepted delivery reaches users, examine whether finance can complete representative reconciliations and whether operational behaviour remains acceptable. The sample exercise informs the output decision; actual use can expose conditions it missed.

The automation discussion in Part 7 considers which checks earn their place in existing review, including the work needed to maintain them.