abap-playbook-skill/templates/playbook-example.md

Development Playbook: EDOC-REFACT-01 — ZEDOC_REPAIR_REPORT test coverage

Status: draft Author: I301710 Model tier for execution: sonnet for phases 5 and 6, opus for phases 1 and 2 Transport: Package:

All lines marked ASSUMED hold placeholder data. Replace them with system data before the agent starts phase 1.

The agent runs the phases in order. Each phase ends with a gate. The agent must not start the next phase before the gate passes. If a gate fails twice, the agent stops and reports. It does not try a third time.

---

0. Context

Business need: ZEDOC_REPAIR_REPORT has no unit tests. The logic sits in the report and reads the database directly, so a test needs a system connection. The refactoring must reach 70% coverage without a change to the behaviour that the user sees.

Related objects (known before analysis):

Object	Type	Role
ZEDOC_REPAIR_REPORT	report	selection screen, logic, output — ASSUMED ~1400 lines
EDOC_HDR	table	eDocument header — ASSUMED
EDOC_STATUS	table	status history — ASSUMED
CL_EDOCUMENT	standard class	status change API — ASSUMED

Out of scope:

• The selection screen fields and their names.
• The ALV output layout.
• Any standard SAP object.
• The repair rules themselves. This change moves logic. It does not correct it.

---

1. Analysis

Input: section 0.

Actions:

1. Read the report structure: FORM routines, local classes, global data.
2. Find a similar refactored report in the package. Record the pattern that it uses for data access and for test doubles.
3. Record which FORM routine reads the database and which one only computes.

Output:

Object	Direction	Caller / callee	Risk if changed
ZEDOC_REPAIR_REPORT	entry	started by user and by job variant EDOC_REP_D — ASSUMED	job variant breaks if the selection screen changes
f_select_documents	callee	reads EDOC_HDR	pure database access, move behind an interface
f_determine_repair	callee	called by f_select_documents	pure logic, move to the processor class
f_apply_repair	callee	calls CL_EDOCUMENT	write access, move behind an interface
f_display	callee	ALV	keep in the report

Naming pattern found in the package — ASSUMED:

• Classes: ZCL_EDOC_<area>_<role>
• Interfaces: ZIF_EDOC_<area>_<role>
• Test classes: local ltcl_<subject> in the class include

Framework pattern found in the package — ASSUMED:

• Data access sits behind an interface. The production class carries the SELECT.
• Test doubles are local classes in the test include.
• The constructor takes the interface. It defaults to the production class.

Gate A:

• Every FORM routine has a category: read, write, or compute.
• The job variant list is complete.
• The naming convention is written down, not assumed.

---

2. Impact analysis

Change	Type	Downstream effect	Mitigation
Move the logic out of the report	behaviour risk	wrong result if a global variable holds state between FORM routines	list every global variable in phase 1 and pass it as a parameter
New interface for the read access	new object	none, the report is the only caller	—
New interface for the write access	new object	CL_EDOCUMENT calls move into one class	one place to check for the update task
The report keeps the selection screen	none	job variant stays valid	do not rename a selection screen field
No existing unit test	none	nothing to break	—

Known risk: the report may run inside an update task. If the write happens in IN UPDATE TASK, the sequence must not change. Confirm this in phase 1 before phase 5 starts.

Gate B:

• Every global variable in the report is listed with its readers.
• The update task behaviour is confirmed, not assumed.
• The selection screen stays unchanged.

---

3. Object plan

3.1 Objects to change

Object	Type	Change	Verification
ZEDOC_REPAIR_REPORT	report	keep the selection screen, the ALV, and the START-OF-SELECTION shell. Delegate the rest to the processor.	run with the job variant, compare the result list with the result before the change

3.2 Objects to create

Object	Type	Responsibility	Package	Naming rule applied
ZIF_EDOC_REPAIR_DATA	interface	declare the read and write operations for repair data		ZIF_EDOC__
ZCL_EDOC_REPAIR_DATA	class	run the SELECT and the status update against the database		ZCL_EDOC__
ZCL_EDOC_REPAIR_PROCESSOR	class	decide which document needs a repair and which repair it needs		ZCL_EDOC__

The processor holds no SELECT. It receives data and returns a decision. This is the condition that makes a database-free test possible.

Gate C:

• Every object has an exact name.
• The processor class has no database access in its plan.
• The package and the transport are set for each new object.

---

4. Coding standards

The agent applies these rules. It does not restate them in the code.

• Clean ABAP naming and structure.
• No comment that restates what the code does.
• No Given/When/Then comment headers in tests.
• Method length: keep below 40 statements.
• No new global variable.
• Exception classes: use the package pattern. Do not create a new base class.
• Text elements for user-facing text.

Project-specific rules recorded in section 1:

• Class and interface names follow Z(CL|IF)_EDOC_<area>_<role>.
• The constructor takes the data interface and defaults to the production class.
• Test doubles are local classes in the test include.

---

5. Implementation

Order:

1. ZIF_EDOC_REPAIR_DATA — create, activate, syntax check.
2. ZCL_EDOC_REPAIR_DATA — implement the interface with the SELECT and the update that phase 1 recorded. Activate, syntax check.
3. ZCL_EDOC_REPAIR_PROCESSOR — move the compute logic from the FORM routines. Activate, syntax check.
4. ZEDOC_REPAIR_REPORT — replace the FORM bodies with calls to the processor. Keep the selection screen and the ALV. Activate, syntax check.

Rules:

• One object per step.
• Do not change an object that section 3 does not list.
• If the implementation needs another object, stop and update section 3 first.
• Move the logic. Do not improve it. A behaviour change here breaks the comparison test in section 8.

Gate D:

• All four objects are active.
• The syntax check returns no error.
• The report holds no SELECT statement.
• No object outside section 3 changed.

---

6. Unit tests

Target coverage: 70% or higher on ZCL_EDOC_REPAIR_PROCESSOR.

Actions:

1. Create a local test double for ZIF_EDOC_REPAIR_DATA in the processor test include.
2. Write the cases below.
3. Run ABAP Unit.

Case	Object	Expected result
document with a status that needs a repair	processor	the processor returns the repair action
document with a status that needs no repair	processor	the processor returns no action
document with a status outside the known set	processor	the processor raises the package exception
empty input table	processor	the processor returns an empty result, no exception
two documents, one needs a repair	processor	the result holds one entry
document already repaired on the same day	processor	the processor returns no action

Gate E:

• All tests pass.
• Coverage on the processor is 70% or higher.
• No test opens a database connection.
• The test double holds no SELECT.

---

7. ATC

Actions:

1. Run ATC with the project variant on the four objects.
2. Report priority 1 and priority 2 findings, grouped by check.
3. Fix each finding, or record the reason for an open finding.

Check	Priority	Object	Decision

Stop rule: if the same finding returns after two fix attempts, the agent stops and reports it.

---

8. Acceptance criteria

• The report started with job variant EDOC_REP_D returns the same document list as before the change. Compare with a saved result list.
• The status update writes the same records as before, in the same sequence, and in the same update task mode.
• The selection screen shows the same fields with the same names.
• A document with an unknown status raises the package exception. The report shows the message and does not dump.
• The ALV layout and the column order stay unchanged.

The first criterion needs a result list from before the change. Save it before phase 5 starts. Without it the criterion is not testable.

---

9. Definition of done

• Gates A to F pass.
• All acceptance criteria pass.
• The transport holds the four objects and no other object.
• The agent produced a change summary.
• Open points are listed, or the list is empty.

---

Token rules for the agent

• Read method signatures and the FORM list before the full report source.
• Read a FORM body only in the step that moves it.
• Do not repeat a read that the tables above already record.
• After each phase, keep the tables and drop the raw source.
• If two attempts at a gate fail, stop.

Change summary (agent fills this at the end)

Object	Type	Action	Reason

Open points: