Stage 02 / 15 minutes / Pairs or individual
Write a specification
Turn the issue and context into observable rules without prescribing the implementation.
- Output
- Change specification
- Support
- One requirement contrast
- Continue when
- All readiness checks pass
Repository for this lesson jhipster/jhipster-sample-app-react at 8c9d248 . All source links, commands and observations refer to this pinned revision.
Orient
Why this stage matters
Explain why write a specification affects confidence in the build.
You can name the decision this stage supports and the risk created by skipping it.
This ties the stage to the lab’s central question: Does the evidence show that posting an operation and changing its account balance form one safe, reviewable outcome?
“Update the balance” does not define signs, precision, ownership, retries or later changes to posted operations. Code written against that sentence can be internally consistent and still implement the wrong product behavior.
Inputs
Use repository sources and accepted artifacts
Identify the accepted evidence and artifacts required for this stage.
You can explain why each source is relevant and exclude material that does not affect the work.
These sources establish what the repository does when operation and balance records can be changed independently. Later claims and tests must trace back to this evidence.
Issue
Use the requested outcome as the boundary, not as a complete requirement.
Context brief
Use the accepted facts, assumptions and open questions from stage 1.
Operation DTO
Check current validation and data shape.
src/main/java/io/github/jhipster/sample/service/dto/OperationDTO.javaDatabase constraints
Check the stored precision and relationships.
src/main/resources/config/liquibase/changelog/20150805125054_added_entity_Operation.xmlAccount schema
Compare balance precision with the operation amount.
src/main/resources/config/liquibase/changelog/20150805124838_added_entity_BankAccount.xmlWorked example
Replace one vague sentence with observable behavior
Study one worked example and identify the judgment behind each step.
You can reproduce the reasoning without copying the example’s conclusion.
The example models one part of the operation-and-balance problem. You apply the same reasoning to the remaining paths and produce evidence another engineer can review.
- Start with: “The system updates the balance when an operation is posted.”
- Name the trigger, the two state changes and the failure condition.
- Write one acceptance example that observes both records before and after the request.
A requirement is testable when two reviewers can agree on the expected result without choosing a class, method or framework.
The worked example resolves only the atomicity case.
Decide
Resolve the behavior the repository cannot define
Separate repository facts from decisions that require human authority.
Each question has an accepted answer or remains blocked with a named owner.
The repository cannot decide credit, debit, retry, ownership or mutation policy. Those decisions define what balance consistency means and what can be judged safe to ship.
- Does a positive amount credit the account and a negative amount debit it?
- What precision is accepted, and can the system round an amount?
- Can a debit take the balance below zero?
- Can a user post to an account the user does not own?
- How should the system handle an identical retry?
- Can posted operations be updated, patched or deleted?
- Can a client edit the account balance directly?
- What response gives the React client the authoritative result?
Use the agent
Use the agent on this repository
Use the coding agent to support write a specification while retaining control of decisions and evidence.
You verified each response before continuing and carried only accepted findings into the artifact.
Bounded prompts help investigate and build the balance change while human checks prevent unsupported agent output from entering the evidence chain.
These are task patterns for the pinned JHipster source, not answer scripts. Replace every bracketed field with accepted repository work. Open every cited path at the pinned revision and review each response before continuing. If you cannot supply a field, return to the earlier artifact.
Decide before prompting
- Use the accepted context brief, not the prior chat, as source material.
- Record who can decide each product question.
Surface missing decisions
The repository describes current behavior. It cannot authorize new product rules.
Read the issue and accepted context brief. List the decisions required before observable behavior can be specified. Include sign rules, precision, ownership, retries and allowed mutations. Do not answer the questions.Assign every question to a person or role. Mark unresolved decisions as blocked.
Draft testable claims
Small, identified claims can be traced into tests, plans and review findings.
Using only accepted decisions, draft observable behavior claims. Give each claim a stable ID. Cover success, rejection and failure behavior. Do not name classes, methods or implementation steps. Preserve unresolved items as BLOCKED with an owner.For each claim, ask what an external observer could see and whether two inputs would distinguish it.
Add concrete examples
Examples reveal sign, rounding and boundary ambiguity that prose can hide.
Add input and outcome examples to each claim. Include a credit, debit, invalid owner, invalid account and repeated request where the accepted decisions support them. Use exact monetary values. Flag any example that requires a new decision.Calculate each expected balance by hand and confirm that no example invents policy.
Audit the change specification
The specification must be complete enough for another engineer to interpret the same way.
Audit the draft specification for ambiguity, contradiction, missing mutation paths, implementation language and unsupported decisions. Cite the affected claim ID. Do not rewrite it.Revise the artifact, then confirm that every audit finding has a disposition.
Create
Produce the change specification for this repository
Create a reviewable change specification from accepted inputs.
The artifact contains every required field and stays within its stated limit.
This artifact records the evidence or decision the next stage needs to move the operation-and-balance change toward a supported release judgment.
- Write a numbered claim for each accepted behavior.
- Add at least one concrete acceptance example for success, rejection and retry.
- Record unresolved decisions with an owner. Do not hide them in notes.
- State implementation and product areas that remain outside the change.
- Check that every claim describes an observable result.
Two pages, including examples and exclusions.
- Purpose
- Definitions
- Behavior claims
- Acceptance examples
- Failure behavior
- Exclusions
- Open decisions and owners
Challenge
Try to disprove the repository-backed work
Find a material weakness before the artifact controls later work.
Each challenge has evidence, an impact and a recorded response.
The challenge tests whether a partial write, duplicate effect, unauthorized operation or unsupported claim could survive the proposed artifact.
Ask another pair to propose one request with no clear result and one pair of conflicting rules. If you are working alone, test each decision question with two different inputs.
Required responseThe authors resolve the ambiguity, record a blocking decision or narrow the claim.
Revise
Use repository evidence before continuing
Resolve findings and make an explicit decision about readiness.
Every readiness check passes, or the work returns to the section that must change.
The gate prevents unresolved balance-consistency risks from flowing into code or supporting a stronger shipping claim than the evidence allows.
Ready to continue when
- The specification addresses create, retry, overdraw, ownership, update, patch, delete and direct balance changes.
- Every accepted claim has an observable result.
- No claim depends on an unstated sign or precision rule.
If a check fails
- Turn general terms such as valid, correct and safe into observable conditions.
- Separate product decisions from implementation choices.
- Record a product decision you are not authorized to make as a blocker with a named owner.
Transfer
Apply the practice to your work
Map this practice to a real codebase, role and delivery decision in your work.
You can name the equivalent artifact, evidence, owner and next use in your team.
The lab succeeds when you can use the same evidence chain to judge an AI-assisted change in a production codebase, beyond this sample’s operation-and-balance problem.
- Name two rules in a current payment flow that engineers often infer instead of documenting.
- Identify where your team records unresolved product decisions.
Record your answer. The lab is complete only when you can name the equivalent practice, artifact and evidence in your work.