Study guide: Practical Part 11. Integration with a Real API: From Specification to Deployment

Topic: Applied Part 11. Integration with a Real API: From Specification to Deployment

Difficulty level: Medium

Estimated study time: 4-6 hours

Prerequisites: Familiarity with SDD concepts (Specify, Plan, Tasks, Implement, Validate) from parts 7-9 of the first volume.

Understanding the principles of command review (part 16 of the first volume).

Basic knowledge of working with CLI (command line) and Python.

General understanding of how webhooks and REST API work.

Learning objectives: Master the local incident handling pipeline: from a raw webhook to a normalized event and readiness check.

Learn to apply the 25-point readiness assessment model to make a decision on auto-remediation admission.

Understand and be able to identify blocking conditions (audit_trace, stateful workloads) before performing real actions.

Master the separation of phases in SDD so that the specification phase does not replace the implementation phase.

Be able to classify API and pipeline errors according to the taxonomy (VALIDATION_ERROR, LLM_CALL_FAILED, etc.) to choose a recovery strategy.

Overview: This chapter is dedicated to practical integration with a real API in the context of incident management and auto-remediation. You will learn how to safely run the pipeline from receiving a raw webhook (Grafana/PagerDuty) to a controlled deployment or restart. The production incident high_memory_usage serves as the main educational case. The chapter demonstrates how to use scripts from examples/real-api/ to normalize data, pass the readiness gate based on a 25-point rubric, and perform a dry-run, ensuring that prohibited actions will be blocked and allowed ones will be strictly justified.

Key concepts: Readiness: Formal pipeline assessment on a 25-point scale. Includes 5 categories (Spec, Implementation, Verification, Process, Security), scored from 0 to 5. The threshold for automatic admission is 23/25. If the score is lower, the pipeline switches to semi-manual mode.

Sdd-phase separation: A methodology that divides the change lifecycle into phases: Specify (user story), Plan (strategy), Tasks (steps), Implement (application), Validate (verification). Protects the system from premature execution of commands ('fix immediately').

Audit trace: A causal log that connects the incoming webhook, user commands (e.g., /sdd:specify), created specifications, and diffs through a unique incident_id. Provides provability and reproducibility of the incident.

Dry-run: Simulation of action execution against a list of pre-approved actions without making real changes to the infrastructure. Allows you to make sure that the action is allowed by the specification.

Error taxonomy: Classification of API failures (e.g., VALIDATION_ERROR, TOOL_EXECUTION_FAILED), which allows the orchestrator to choose the right recovery strategy (stop, retry, degrade, escalate) instead of outputting a generic 'failed' status.

Degraded mode: A system state in which auto-remediation is disabled (e.g., when the LLM fails or the Readiness score is low), but the system continues to save evidence and suggest steps to the operator for manual confirmation.

Practice exercises: Name: Normalizing incoming webhooks

Problem: You have received raw payloads from the Grafana and PagerDuty monitoring systems. You need to run the normalization script and make sure that the output JSON matches the reference incident event field by field.

Solution: 1. Navigate to the example directory: cd book2/examples/real-api

1. Run the normalization script specifying the paths to the fixtures:

python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json

1. Make sure the script completes with return code 0. If the code is not zero, check stderr for schema validation errors.

Complexity: beginner

Name: Readiness gate check

Problem: Evaluate three different system states using the readiness check script: passing (24/25), audit failure (22/25), and stateful workload failure (24/25, but no backup).

Solution: Run the scripts one by one and analyze the output:

1. python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json (Expected: code 0, PASS).
2. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json (Expected: code 1, BLOCK due to audit_trace_coverage).
3. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json (Expected: code 1, BLOCK due to no confirmed backup for stateful).

Complexity: intermediate

Name: Dry-run of allowed and prohibited actions

Problem: Use the dry-run script to check two actions against the high_memory_usage specification. The first action (restart_pod) should be allowed, and the second (delete_namespace) should be blocked as unauthorized.

Solution: 1. Run the allowed action: python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod Make sure the return code is 0 and stdout contains PASS.

1. Run the prohibited action:

python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace Make sure the return code is 1 and stderr indicates the reason for blocking (the action is not among pre-approved).

Complexity: intermediate

Name: Filling out the readiness rubric for your own case

Problem: Based on the 25-point model, evaluate a hypothetical (or your current) pipeline. Fill in the table of 5 categories, indicate evidence artifacts, and identify blocking conditions to reach the 23/25 threshold.

Solution: 1. Create a table with columns: Category, Score, Evidence artifact, Reason for reduction.

1. Go through Spec, Implementation, Verification, Process, Security.
2. For Spec, make sure there are WHY/WHAT/constraints.
3. For Security, check for rollback and emergency stop.
4. If the total is below 23/25, make a list of changes (for example: 'Add a formal escalation trigger', 'Implement dry-run for the scale-up branch').

Complexity: advanced

Case studies: Name: Production incident high_memory_usage

Scenario: The Grafana monitoring system records memory_percent=93 on the api-7b4 pod in the appointments-api namespace for 10 minutes. PagerDuty escalates the incident level to critical. A webhook arrives, initiating the system's auto-remediation process.

Challenge: It is necessary to reduce memory consumption (prevent OOMKill) without disrupting the service. Running an automatic script that simply restarts or deletes resources is risky — you can lose stateful data or expand the blast radius of the error. The system must understand whether it is allowed to act automatically, and what the minimum action is.

Solution: 1. Normalization: The normalize_webhook.py script merges data from Grafana and PagerDuty into a single incident_event (incident_id=HM-2026-05-17-01).

1. Readiness gate: check_readiness.py evaluates the pipeline. If audit_trace is below 1.0 or the workload is stateful without a backup — the action is blocked until human intervention.
2. Dry-run: dry_run.py checks the restart_pod action against the specification (pre-approved actions).
3. Execution: If readiness >= 23/25 and dry_run returned PASS, a restart is initiated with mandatory monitoring of two windows and a rollback path available after 6 minutes.

Result: The automated pipeline safely isolated the problem. The allowed action was performed with a full audit (audit trail). The pipeline's attempt to perform an unauthorized or dangerous action was strictly blocked by the security gate, which prevented a potential failure of the entire service.

Lessons learned: Specify should not contain specific commands (e.g., kubectl delete); it should describe WHY and WHAT.

The blast radius must be limited (e.g., only one specific pod).

System failures (e.g., an LLM problem) should put it into degraded mode, not stop it completely without explanation.

Full auto-remediation without human participation (human-review) on the critical path remains a risky practice (frontier).

Related concepts: Readiness Model

Audit Trace

Dry-run

Error Taxonomy

Degraded Mode

Study tips: Start by running the ready-made scripts in book2/examples/real-api/. Do not try to immediately set up a full Kubernetes or GitOps — the logic of the scripts is what matters for the learning pass.

Pay special attention to the readiness_block_*.json fixtures. Try changing values in them (for example, raising audit_trace_coverage to 1.0) and see how the result of check_readiness.py changes.

Compare the 'Bad' and 'Good' examples of specifications (Specify) from the text. Understand why the choice of a specific implementation at the specification stage blocks planning flexibility.

Always record your runs and decisions (for example, in capstone/readiness.md). Integration with APIs is not only code, but also evidence artifacts (audit trace).

Additional resources: Learning scripts (examples/real-api): A folder with a ready-to-run pipeline without external dependencies (Python stdlib).

Github spec kit: A framework for the practical application of the Specify → Plan → Tasks → Implement phases.

Appendix d (threshold calibration): Section D.5 contains tables for configuring readiness thresholds (Low/Default/High) for different types of production environments.

Book/part-12-mvp.md: Reference material from the first volume describing work with SQLite, on the basis of which the high_memory_usage scenario is built.

Summary: In this chapter, you learned how to turn the chaos of real API webhooks (Grafana, PagerDuty) into a strict, manageable, and provable auto-remediation process. The main takeaway: any automatic action must pass through the Readiness Gate. The use of the 25-point assessment model and the mandatory dry-run ensure that the system does not go beyond the specified blast radius. SDD phase separation and the audit trace provide transparency: if the system cannot prove its readiness (for example, due to an incomplete audit), it is switched to a safe semi-manual mode.