> ## Documentation Index
> Fetch the complete documentation index at: https://sdlc-rstack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent 10 — Summary

> Technical lead handoff agent. Reads every upstream contract and produces PROJECT_SUMMARY.md plus summary.json — the pipeline's decision log and defect analysis.

<Info>
  **File:** `agents/sdlc/10-summary.md` · **Model:** Sonnet · **Tools:** Bash, Read, Write
</Info>

## Purpose

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.

<Note>
  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.
</Note>

## 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_decision` events (`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`

For every defect it records `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.

```json theme={null}
// .rstack/runs/<run_id>/artifacts/summary.json
{
  "project_name": "...",
  "built": "...",
  "tech_stack": {},
  "architecture_decisions": [],
  "open_risks": [],
  "next_steps": [],
  "defect_analysis": {
    "source": ["events.jsonl", "tasks/*/validation.json"],
    "defects": [
      {
        "task_id": "...",
        "stage_id": "...",
        "kind": "missing_evidence|failed_check|budget_overrun|malformed_contract",
        "discoverer": "<validator profile, guardrail rule, or check name>",
        "severity": "BLOCKED|FAIL|NEEDS_CONTEXT",
        "attempts": 0,
        "first_seen": "<ISO 8601>",
        "fixed_at": "<ISO 8601 or null>",
        "age_at_fix_minutes": null,
        "cause_bucket": "people|process|tools|requirements"
      }
    ],
    "totals": { "by_kind": {}, "by_discoverer": {}, "by_severity": {}, "by_cause_bucket": {} },
    "retry_rollup": { "scheduled": 0, "exhausted": 0, "human_required": 0 },
    "metrics": [
      { "name": "defect_count", "value": 0, "scope": "project" },
      { "name": "cause_bucket_distribution", "value": {}, "scope": "process" },
      { "name": "cost_usd", "value": null, "scope": "project", "reason": "..." },
      { "name": "context_tokens", "value": null, "scope": "project", "reason": "..." }
    ]
  },
  "pipeline_complete": true,
  "status": "PASS"
}
```

## 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.

| Status               | Meaning                                                                   |
| -------------------- | ------------------------------------------------------------------------- |
| `DONE`               | `summary.json` and `PROJECT_SUMMARY.md` written, pipeline marked complete |
| `DONE_WITH_CONCERNS` | Summary written but some upstream contracts were missing or partial       |
| `BLOCKED`            | No upstream contracts found — escalates if more than 3 are missing        |
| `NEEDS_CONTEXT`      | One question about an open risk or an undocumented decision               |

## Where it sits in the pipeline

Stage 10 runs after `09-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.

## Related

* [Pipeline Overview](/sdlc-pipeline/overview)
* [Agent 09 — Deployment](/sdlc-pipeline/deployment)
* [Agent 08 — Testing](/sdlc-pipeline/testing)