Initial commit: ABAP playbook skill
This commit is contained in:
Erhan Keseli
253
templates/playbook-example.md
Normal file
253
templates/playbook-example.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# 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: <TR number>
|
||||
Package: <eDocument 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 | <package> | ZIF_EDOC_<area>_<role> |
|
||||
| ZCL_EDOC_REPAIR_DATA | class | run the SELECT and the status update against the database | <package> | ZCL_EDOC_<area>_<role> |
|
||||
| ZCL_EDOC_REPAIR_PROCESSOR | class | decide which document needs a repair and which repair it needs | <package> | ZCL_EDOC_<area>_<role> |
|
||||
|
||||
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:
|
||||
-
|
||||
224
templates/playbook-template.md
Normal file
224
templates/playbook-template.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Development Playbook: <KEY> — <short title>
|
||||
|
||||
Status: draft | approved | in progress | done
|
||||
Author: I301710
|
||||
Model tier for execution: <opus | sonnet | haiku>
|
||||
Transport: <TR number>
|
||||
Package: <package>
|
||||
|
||||
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:
|
||||
<two or three sentences. no background prose.>
|
||||
|
||||
Related objects (known before analysis):
|
||||
| Object | Type | Role |
|
||||
|---|---|---|
|
||||
| ZCL_... | class | ... |
|
||||
| ZBR_... | report | ... |
|
||||
|
||||
Out of scope:
|
||||
- <what this change must not touch>
|
||||
|
||||
---
|
||||
|
||||
## 1. Analysis
|
||||
|
||||
Input: section 0.
|
||||
|
||||
Actions:
|
||||
1. Run `sap_object_members` for each object in the table above. Read a method
|
||||
body only when a gate needs it: `sap_pull_source` with `element=<name>`.
|
||||
2. Run `sap_object_members` on two or three similar objects in the package.
|
||||
Record the naming pattern and the framework pattern. Do not read bodies.
|
||||
3. Run `sap_usage_references` for each object that changes. Record the call
|
||||
chain in the table.
|
||||
|
||||
Output — fill this table:
|
||||
|
||||
| Object | Direction | Caller / callee | Risk if changed |
|
||||
|---|---|---|---|
|
||||
|
||||
Gate A:
|
||||
- [ ] Every object in scope has a known caller list.
|
||||
- [ ] The naming convention is written down, not assumed.
|
||||
- [ ] No open question remains that needs a system read.
|
||||
|
||||
If a gate item fails, the agent asks one question. It does not guess.
|
||||
|
||||
---
|
||||
|
||||
## 2. Impact analysis
|
||||
|
||||
Actions:
|
||||
1. List the objects that change behaviour.
|
||||
2. List the objects that change signature. A signature change needs a caller
|
||||
update list.
|
||||
3. List the DDIC and customizing dependencies.
|
||||
4. State the effect on existing unit tests.
|
||||
|
||||
Output:
|
||||
|
||||
| Change | Type | Downstream effect | Mitigation |
|
||||
|---|---|---|---|
|
||||
|
||||
Gate B:
|
||||
- [ ] Every signature change has a complete caller list.
|
||||
- [ ] The effect on existing tests is stated for each change.
|
||||
- [ ] No change touches an object in the "out of scope" list.
|
||||
|
||||
---
|
||||
|
||||
## 3. Object plan
|
||||
|
||||
### 3.1 Objects to change
|
||||
|
||||
| Object | Type | Change | Verification |
|
||||
|---|---|---|---|
|
||||
|
||||
### 3.2 Objects to create
|
||||
|
||||
| Object | Type | Responsibility | Package | Naming rule applied |
|
||||
|---|---|---|---|---|
|
||||
|
||||
Each new object needs one sentence of responsibility. If the sentence needs the
|
||||
word "and", split the object.
|
||||
|
||||
Gate C:
|
||||
- [ ] Every object has an exact name. No placeholder names remain.
|
||||
- [ ] Every object has one responsibility.
|
||||
- [ ] 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. Keep only comments that explain
|
||||
a non-obvious reason.
|
||||
- No Given/When/Then comment headers in tests.
|
||||
- Method length: keep below 40 statements. Split if longer.
|
||||
- No new global variable.
|
||||
- Exception classes: use the pattern that section 1 recorded, not a new one.
|
||||
- Text elements for user-facing text. No hardcoded literal.
|
||||
|
||||
Project-specific rules recorded in section 1:
|
||||
- <naming pattern>
|
||||
- <framework pattern>
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation
|
||||
|
||||
Actions, in order, for each object in section 3:
|
||||
1. Change one method with `sap_push_element` (use `signature` when the
|
||||
declaration changes too). Push a full source only for a new object, with
|
||||
`sap_push_source` — it runs lock, write, unlock, and activate in one call.
|
||||
2. Run `sap_check_object` for the object.
|
||||
3. Fix errors before the next object.
|
||||
|
||||
Rules:
|
||||
- One object per step. Do not create several objects and activate them together.
|
||||
- Do not change an object that section 3 does not list.
|
||||
- If the implementation needs an object that section 3 does not list, stop.
|
||||
Return to section 3 and update it first.
|
||||
|
||||
Gate D:
|
||||
- [ ] Every object in section 3 is active.
|
||||
- [ ] The syntax check returns no error.
|
||||
- [ ] No object outside section 3 changed.
|
||||
|
||||
---
|
||||
|
||||
## 6. Unit tests
|
||||
|
||||
Target coverage: <70% or higher>
|
||||
|
||||
Actions:
|
||||
1. Write tests for each public method that section 3 lists.
|
||||
2. Keep the tests free of database access. Use test doubles.
|
||||
3. Run ABAP Unit. Record the result.
|
||||
|
||||
Test cases to cover:
|
||||
| Case | Object | Expected result |
|
||||
|---|---|---|
|
||||
|
||||
Gate E:
|
||||
- [ ] All tests pass.
|
||||
- [ ] Coverage meets the target.
|
||||
- [ ] No test needs a database connection.
|
||||
|
||||
---
|
||||
|
||||
## 7. ATC
|
||||
|
||||
Actions:
|
||||
1. Run `sap_check_object` with the project ATC variant and `runUnitTest=true`.
|
||||
2. Report only priority 1 and priority 2 findings. Group them by check.
|
||||
3. Fix each finding, or record why the agent does not fix it.
|
||||
|
||||
Output:
|
||||
|
||||
| Check | Priority | Object | Decision |
|
||||
|---|---|---|---|
|
||||
|
||||
Gate F:
|
||||
- [ ] No priority 1 finding remains open.
|
||||
- [ ] Every open priority 2 finding has a written reason.
|
||||
|
||||
Stop rule: if the same ATC finding returns after two fix attempts, the agent
|
||||
stops and reports the finding. It does not try a third fix.
|
||||
|
||||
---
|
||||
|
||||
## 8. Acceptance criteria
|
||||
|
||||
The change is correct when all of these are true:
|
||||
|
||||
- [ ] <observable behaviour 1>
|
||||
- [ ] <observable behaviour 2>
|
||||
- [ ] <negative case: what must not happen>
|
||||
|
||||
Each criterion must be testable from outside the code. "The code is clean" is
|
||||
not a criterion.
|
||||
|
||||
---
|
||||
|
||||
## 9. Definition of done
|
||||
|
||||
- [ ] Gates A to F pass.
|
||||
- [ ] All acceptance criteria pass.
|
||||
- [ ] The transport holds every changed object and no other object.
|
||||
- [ ] The agent produced a change summary: object, type, one line of reason.
|
||||
- [ ] Open points are listed, or the list is empty.
|
||||
|
||||
---
|
||||
|
||||
## Token rules for the agent
|
||||
|
||||
- `sap_object_members` before source. `element=` before a class. Read a full
|
||||
include only when a gate needs the body, and write the reason into this
|
||||
playbook.
|
||||
- Ask for a targeted change. Do not rewrite a whole object to fix one method.
|
||||
- Do not repeat a read that this playbook already recorded. The tables above
|
||||
are the memory.
|
||||
- After each phase, keep the tables and drop the raw source from the working
|
||||
context.
|
||||
- If two attempts at a gate fail, stop. A third attempt costs more than a
|
||||
question.
|
||||
|
||||
## Change summary (agent fills this at the end)
|
||||
|
||||
| Object | Type | Action | Reason |
|
||||
|---|---|---|---|
|
||||
|
||||
Open points:
|
||||
-
|
||||
Reference in New Issue
Block a user