Scenario 04: Update Corporate Architecture Artifacts¶

Scenario Overview¶

Pre-conditions¶

• Solution design for NTK-10001 (Add Elevation Profile Data) is complete and approved
• Solution design located at work-items/tickets/_NTK-10001-elevation-profile-data/NTK-10001-solution-design.md
• Swagger spec for svc-trail-management exists at services/svc-trail-management.yaml
• PlantUML component diagram exists in diagrams/
• AI understands that corporate artifacts are the source of truth

Exact Prompt to Use¶

"The solution design for NTK-10001 (Add Elevation Profile Data) is approved. Update the corporate architecture artifacts: modify the svc-trail-management Swagger spec to add the elevation fields to the TrailDetail schema and trail response endpoint. Update the relevant PlantUML component diagram to show the new data flow. Create a commit message summarizing the changes."

Expected AI Actions¶

1. Read Solution Design: Review NTK-10001 solution design to understand:
2. What elevation fields need to be added
3. Which schema (TrailDetail) is affected
4. Which endpoint returns trail data with elevation

5. Any new dependencies or data flows

6. Modify Swagger Spec (svc-trail-management.yaml):

7. Add elevation fields to the TrailDetail schema:
   • elevationProfile (array of elevation data points)
   • elevationGain (number, total elevation gain in meters)
   • elevationLoss (number, total elevation loss in meters)
   • maxElevation (number, peak elevation in meters)
   • minElevation (number, minimum elevation in meters)
8. Add proper types, descriptions, and examples

9. Ensure fields appear in the GET trail detail response

10. Update PlantUML Diagram:

11. Add elevation data flow to component diagram
12. Show data source for elevation data (if new integration)

13. Ensure diagram syntax is valid

14. Verify Consistency:

15. Swagger changes match what solution design specified
16. No orphaned references or broken schemas

17. PlantUML diagram reflects the Swagger changes

18. Draft Commit Message:

19. Clear summary referencing NTK-10001
20. List of changed files
21. Brief description of what was added

What to Watch For¶

• Does the AI read the solution design FIRST before making changes?
• Are the OpenAPI spec changes valid (proper types, required fields, descriptions)?
• Does the PlantUML diagram use correct syntax (compilable)?
• Are the changes LIMITED to what the solution design specified (no scope creep)?
• Does the commit message follow conventional format?

Quality Rubric¶

Score each criterion 1-5:

• [ ] OpenAPI Validity: Swagger spec changes are valid OpenAPI 3.0 syntax
• [ ] Field Quality: New fields have proper types, descriptions, and examples
• [ ] PlantUML Syntax: Diagram compiles with valid PlantUML syntax
• [ ] Design Consistency: Changes match exactly what solution design specified
• [ ] Commit Message: Commit message is clear, references ticket, and lists changes

Maximum Score: 25

Token Cost Tracking¶

Validation Steps (Manual)¶

After the AI completes the task, manually verify:

1. Swagger Validation: Run the spec through an OpenAPI validator
2. PlantUML Compilation: Render the diagram to confirm valid syntax
3. Diff Review: Check that only intended fields were added (no unrelated changes)
4. Cross-reference: Confirm all fields in solution design appear in the spec

Notes¶

• This scenario tests precision and restraint -- the AI should change only what the design specifies
• Scope creep (adding fields not in the design) should reduce the quality score
• This is a common task that is tedious for humans but should be straightforward for AI
• The commit message quality reflects the AI's understanding of change management