Reference tag: Second_IT — commit «feat: add barcode support and enhance domain logic»
In episode 1, the AI revealed its first limitation: left to its own devices, it codes everything immediately, without any iterative discipline. The solution found was mechanical—breaking it down into baby steps. But a poorly framed baby step is still a step in the wrong direction. Episode 2 recounts what happened when we stopped correcting the AI as it went along and instead imposed a framework on it from the outset. complete methodological framework Requirements engineering (IREB).
1. The symptom: a good idea, poorly conceived
The Product Owner announces their intention to define the next feature: borrowing. The first reflex to correct: not jumping into the code. The shift in approach is immediate—an explicit move into the role of Business Analyst, with a simple guiding principle, but one that AI never spontaneously respects:
Separate the problem space (the profession, the real library) from the solution space (the BiblioCQRS software).
That's the whole point of this episode: without this safeguard, AI constantly confuses "what the library does" and "what the program should do".
2. Diagram No. 1 — Who are the stakeholders, and what do they really want?
The first problem observed was a flat stakeholder map, lacking hierarchy and conflicting interests. The Product Owner's response was two-step: a relational diagram, followed by an expectations/risks/ROI matrix.
flowchart TD
DIR[Direction de la Bibliothèque]
BIB[Bibliothécaire / Documentaliste]
US[Usager / Adhérent]
DIR -->|" Lien hiérarchique / Employeur "| BIB
DIR -->|" Recherche la satisfaction "| US
BIB -->|" Accompagne et sert "| US
| Stakeholder | Expectations | Risks | KING |
|---|---|---|---|
| Library Management | Reliable statistics, compliance with regulations | Financial loss (theft), customer dissatisfaction | Data-driven management (CQRS Query) |
| Librarian | Fast, reliable tool | Complexity, wasted time at the counter | Time saved, less operational stress |
| Member | Borrow quickly, transparent rules | Forgetting dates, unjustified blockage | Seamless experience, guaranteed access |
This table is not just filler: it is what later justifies why certain business rules (quota, lateness tolerance) must exist — they stem directly from the risk identified here for Management and the Librarian.
3. Diagram #2 — Do not confuse the library and the software
A second typical AI error is that it designs a system where the user "interacts" with the software as if they were directly borrowing a book from an interface. The product owner corrects this: the computer system has never seen a book. It only exists through the librarian's input.
flowchart TD
subgraph Metier ["La Bibliothèque (Système Métier)"]
US((Usager))
BIB((Bibliothécaire))
LIVRE[Exemplaires Physiques]
US -->|" Rend / Emprunte physiquement "| LIVRE
US -->|" Demande au guichet "| BIB
end
subgraph Solution ["Périmètre de la Solution"]
BiblioCQRS[Système Informatique BiblioCQRS]
end
BIB -->|" Saisie des actes (Emprunts, Retours, Catalogue) "| BiblioCQRS
US -.->|" Notifications / Consultation (Futur) "| BiblioCQRS
It's a trivial pattern on the surface. But it's precisely the kind of nuance that an AI, optimizing to "produce a plausible diagram," erases first if it's not explicitly forced to do so.
4. A gap discovered through further investigation: the unidentified copy
By setting up the nominal borrowing scenario (the librarian provides the copy ID and the member ID), the PO asks a simple question that changes everything:
«"Does your documentation indicate that the copies currently do not have an explicit ID?"»
Honest answer: no. The existing system didn't allow us to distinguish which specific physical copy was borrowed. This isn't a minor detail—without an identifier, no loan rules can be implemented. The IREB discipline pays off immediately: we document the shortage (Elicitation Plan) rather than surreptitiously fixing it in the code, and we create a dedicated User Story (US-CAT-03 : to identify a copy by an explicit ID, barcode or RFID).
The consequence is directly visible in the commit. Second_IT : «feat: add barcode support and enhance domain logic». The documented deviation precedes the code, not the other way around.
5. Diagram #3 — From business objective to use case
Another adjustment made by the Product Owner: the objectives tree didn't speak the same language as the backlog (no shared Epics). Strict alignment was established: Business Objective → Epic → Use Case.
mindmap
root((Exploiter une bibliothèque))
Epic 1_ Gestion du Catalogue
Référencer un nouvel ouvrage abstrait
Ajouter un exemplaire physique
Identifier un exemplaire par ID
Epic 2_ Gestion des Adhérents
Inscrire un adhérent
Epic 3_ Gestion des Prêts
Enregistrer un emprunt
Enregistrer un retour
flowchart LR
Actor((Bibliothécaire))
subgraph "Gestion du Catalogue"
direction TB
UC1([Référencer un nouvel ouvrage abstrait])
UC2([Ajouter un exemplaire physique])
end
subgraph "Gestion des Prêts"
direction TB
UC3([Enregistrer un emprunt])
UC4([Inscrire un adhérent])
end
Actor --> UC1
Actor --> UC2
UC2 -. " << require >> " .-> UC1
Actor --> UC3
Actor --> UC4
UC3 -. " << require >> " .-> UC4
UC3 -. " << require >> " .-> UC2
The arrows << require >> These are not cosmetic: they formalize that a loan cannot be registered without an existing copy and a member. Without this framework, nothing prevented the AI from generating a loan endpoint completely disconnected from the rest of the domain.
6. The persona error: when "the System" becomes an actor
The most instructive reframing of the iteration concerns the writing of User Stories. The AI had written blocking User Stories ("Quota reached", "Too many delays") with, as a persona, the System. The PO stops everything:
The "System" cannot be the actor in a User Story, as it does not derive any business value from it. The User Story must be considered from the perspective of the operational actor.
Correction: the US are rewritten from the point of view of the Documentalist, Who wants to be prevented to take out the loan, in order to guaranteeing equitable access to resources (quota) and the smooth flow of works (delays). A seemingly innocuous grammatical shift, which in reality forces the expression of business value — exactly what the AI, focused on technical functionality, had omitted.
7. Restructure rather than pile up
Documentation deemed too monolithic → split into five specialized files under docs/requirements/ : vision/context, glossary (ubiquitous language), scenarios/rules, elicitation plan, backlog. Each file has a unique responsibility — the same logic of separation of concerns applied to code, applied to documentation.
8. Semantic granularity: Business Case, Use Case, User Story
The final, most subtle adjustment: the PO rejects the verb "Manage" ("Manage loans"), deemed too broad, and distinguishes:
- THE Business Case : the end-to-end business process («Operate a loan»); ;
- THE Use Case : the unitary interaction of an actor with the system at a given moment T ("Accept a loan", "Make a return") — documentation perennial ;
- there User Story : a planning artifact short-lived, which disappears once implemented.
A concrete consequence of this is that the lending domain, which was initially planned to be coded as a single "loan management" function, is broken down into two distinct temporal Use Cases. This is precisely the kind of segmentation that, downstream, prevents the AI from recreating the trap of episode 1—an aggregation that tries to do everything at once.
9. Industrialize reframing: skills, not repetitions
Repeating the same corrections in every conversation isn't framing, it's a way of avoiding the problem. The Product Owner poses the question that concludes the iteration from a methodological standpoint:
How can we make all these rules permanent (no "System" persona, IREB traceability, automatic history) so that we no longer have to repeat them in the future?
Answer: the creation of a skill business-analyst-ireb, which encapsulates these golden rules and makes them reusable on demand, for any future project. Then, when it comes time to move into production, a second skill, techlead-bdd-tdd, This time, the coding methodology is fixed: Double Loop TDD (BDD outside, strict TDD inside), Clean Architecture, TDA, YAGNI.
flowchart LR
A[Scénario Gherkin] -->|Rouge| B[Step Definitions]
B --> C{Domaine seul<br/>pas de Spring, pas de DB}
C -->|TDD interne: Red/Green/Refactor| D[Code de production]
D --> E[Scénario BDD Vert]
10. What this changes compared to episode 1
Episode 1 concluded: «"It's up to the developer to stop it."». Episode 2 goes further: it's no longer just about slowing down AI along the way, but about giving it, upstream, a sufficiently rigorous business grammar so that it no longer has the opportunity to stray. Each reframing by the Product Owner—stakeholders, business/software boundary, copy identity, Epic → Use Case traceability, user story personas, Business Case / Use Case / Use Case granularity—is not a one-off correction: it's a rule that survives, encapsulated in a skill, beyond the conversation that gave rise to it.
The commit Second_IT This is proof by code that this framing work was not just paperwork: the barcode support for the copy, identified as a deficiency as early as step 3 of the workshop, is delivered and tested (integration tests on WorkRepositoryAdapter And WorkCommandController).
11. The prioritized backlog (US-CAT, US-ADH, US-PRT)
Here is the backlog as it emerged from the workshop, translated into a table after the refocusing on document modularity (step 4). The blocking User Stories (US-PRT-02, US-PRT-03) have already been written from the Documentalist's perspective, in accordance with the refocusing on personas (section 6):
| ID | Epic | Inasmuch as… | I want… | In order to… | Status |
|---|---|---|---|---|---|
| US-CAT-01 | Catalog | Librarian | Add an abstract reference (ISBN, Title, Author) | Prepare the catalog to receive copies | Implemented |
| US-CAT-02 | Catalog | Librarian | Add a physical copy for a given work | Add it to the loanable stock | Implemented |
| US-CAT-03 | Catalog | Librarian | Enter the unique identifier (barcode/RFID) when adding a copy | To enable its individual physical traceability | Implemented (Second_IT) |
| US-ADH-01 | Members | Documentalist | Register a new member in the system | Allowing him to start borrowing | To do |
| US-PRT-01 | Loans | Documentalist | Record a nominal loan of one copy from a member | Entrust him with the task for 3 weeks (managed by the system) | To do |
| US-PRT-02 | Loans | Documentalist | Being blocked if I try to register a loan for a member who has reached their quota (5) | To ensure that all members have access to a rich selection of books | To do |
| US-PRT-03 | Loans | Documentalist | I get blocked if I try to register a loan for a member with more than 1 book overdue. | Facilitate the rapid return of copies in circulation | To do |
Only three lines turn green in this iteration: US-CAT-01, US-CAT-02 And US-CAT-03, The last one being directly the translation of the gap uncovered in step 4 (the copy without identity). The rest — members and loans — remains framed but not coded: this is the whole point of episode 3.
12. The CRUD matrix of what is actually implemented
The traceability matrix below incorporates the architecture documentation (01_use_cases_crud.md). Alone UC-CAT-01 (Reference a work), in bold, corresponds to code delivered in Second_IT ; lines related to Loans (in italics (in the project documentation) remain anticipated use cases, not yet covered by a single domain name:
| Information Entity | Use Case (UC) | C (Create) | R (Read) | U (Update) | D (Delete) |
|---|---|---|---|---|---|
| Work | UC-CAT-01 (Reference a work) — implemented | X (Creation) | X (Uniqueness validation) | X (Example added) | |
| UC-PRT-01 (Take into account borrowing) — future | X | ||||
| Copy | UC-CAT-01 (Reference a work) — implemented | X (Physical addition + barcode) | |||
| UC-PRT-01 / UC-PRT-02 — future | X | X (Change of status) | |||
| Member | UC-PRT-01 (Take into account borrowing) — future | X (Quota Verification) | |||
| Loan | UC-PRT-01 (Take into account borrowing) — future | X (Create) | |||
| UC-PRT-02 (Perform restitution) — future | X | X (Close) |
Only two entities — Work And Copy — have a C/R/U column actually backed by production code and integration tests (WorkRepositoryAdapterTest, Work Command Controller Test). The rest of the matrix, in italics, already documents what is expected so as not to start from a blank page in the next episode — it is the IREB that prepares the ground before the AI touches the code.
To follow
Episode 3 : the switch to TechLead. How Double Loop TDD was applied to the infrastructure layer to loop the vertical slice of the domain — and what AI, delivered to the code this time with a solid business framework behind it, did better (and worse) than in episode 1.
Leave a Reply