File:
agents/sdlc/10-summary.md · Model: Sonnet · Tools: Bash, Read, WritePurpose
The summary agent is the last artifact of the pipeline. It writes the handoff document for the engineer who joins three months later and finds no context — the decision log that stands alone: what was built, why the key architectural decisions were made, what the known risks are, and what to do first. It also produces a defect analysis mined from the run’s own event log, so a run you don’t learn from isn’t a run you repeat.Core principle from the agent prompt: if a critical architectural decision is not in this document with its rationale, it will be reversed by the next engineer who doesn’t know why it was made.
How it works
Inputs — every upstream contract, read first. Before writing a word the agent reads all prior stage artifacts from$RSTACK_RUN_DIR/artifacts/: environment_report, requirement_spec, plan, system_design, code_report, test_report, deployment_report. It’s instructed to identify the 2 architectural decisions with the highest reversal risk and document those first, with full rationale.
Defect analysis input — the event log, never memory. The agent mines $RUN_BASE/events.jsonl and every tasks/*/validation.json for the real record of what went wrong during the run:
retry_decisionevents (task_id,stage_id,attempt,max_attempts,retry_recommendation,action,next_status,reason,issues)- Outcome events:
task_retry_scheduled,task_retry_exhausted,task_human_context_required,task_blocked_by_validator - Guardrail events:
guardrail_triggered(limit_name,current_value,limit_value),guardrail_overridden
kind, discoverer (which validator profile, check, or guardrail rule caught it — this distribution is what matters, since a defect caught here is cheap and the same defect found in production is not), severity (BLOCKED > FAIL > NEEDS_CONTEXT), and age-at-fix (first failing event timestamp vs. the passing validation for the same task; null if never fixed, which also routes it into open_risks).
Repeated failures are grouped Ishikawa-style into four cause buckets — people, process, tools, requirements — with counts rolled up in totals.by_cause_bucket and the dominant bucket getting one sentence of analysis in the human report.
Honest nulls, not fabrication. Cost and context-token metrics are written as null with an explicit "reason" field rather than invented — the agent prompt is explicit that a fabricated metric is itself a defect. Every metric is tagged "scope": "project" (this run) or "scope": "process" (trend data the Business Hub trends page consumes across runs).
Brownfield adoption. If the run manifest has "mode": "adopt" and adoption_report.json exists, upstream baselines were harvested by rstack-agents adopt, not generated fresh — those artifacts carry "source": "brownfield-adoption" with adopted_at/evidence fields. The summary must separate “Baseline (adopted)” from “Built this run,” summarize harvested baselines against their evidence rather than second-guessing them, and report adoption gaps (e.g. “tests detected, NOT executed”) verbatim as open risks. A pure adoption run is expected to emit only adoption_harvested events and a near-empty defects array.
Outputs
Written to$RSTACK_RUN_DIR/artifacts/summary.json and PROJECT_SUMMARY.md (repo root).
PROJECT_SUMMARY.md (human-readable) covers: what was built, an architecture-decisions table (decision, rationale), how to run locally, how to deploy, known issues and risks, defect analysis (what failed, who caught it, dominant cause bucket), and next steps / backlog.
Quality self-check and status
Before reporting DONE the agent verifies:PROJECT_SUMMARY.md has “how to run locally” and “how to deploy” with actual commands; every architecture decision has rationale; open risks carry severity; every defect_analysis.defects entry traces to a real event or validation file; every metric is scope-tagged and every null carries a "reason"; and, on an adopted run, baseline claims are cited to adoption evidence.
Where it sits in the pipeline
Stage 10 runs after09-deployment (deployment artefacts + deployment_report.json) and before 11-feedback-loop (retrospective / maintenance taxonomy). It is the pipeline’s release-readiness capstone — the point where every prior contract (00 through 09) gets folded into one decision log — and its defect analysis feeds directly into what 11 reflects on.