--- name: context-summary-writing description: > Use this when an agent finishes work and must publish its context summary for downstream consumers, when publishing an early DRAFT for same-wave peers, preserving revision history across re-runs, or marking assumptions tied to another agent's unfinished output. Covers the 200-line cap, Generated/Run header, revision history, and ASSUMPTION / DRAFT markers. Triggers: context summary, summary, header, revision history, ASSUMPTION, DRAFT, downstream handoff, 200-line. --- # Context Summary Writing Provides the canonical format, content rules, and revision protocol for context summary files that agents write to `docs/architecture/context/` or `docs/detailed-design/context/` for downstream consumption. ## When to Activate - When a design agent finishes work and writes its context summary - When a design agent needs to publish an early draft for same-wave peers - When a re-run occurs and the agent must preserve revision history - When marking assumptions that depend on another agent's unfinished output - When deciding what to include in the summary versus reference from full output - Used by: all design agents (system-decomposer, api-designer, infrastructure-architect, database-architect, pattern-advisor, component-designer, data-model-designer, sdk-designer, interface-designer, algorithm-designer, concurrency-designer, coding-guidelines-generator) ## File Locations | Phase | Directory | Naming Pattern | |-------|-----------|----------------| | Architecture | `docs/architecture/context/` | `-summary.md` | | Detailed Design | `docs/detailed-design/context/` | `-summary.md` | Review agents (Wave 3/4) do NOT write context summaries. They write to their respective `reviews/` directories but still use the `` header. ## Required Header Every context summary MUST start with this exact comment format on line 1: ```markdown ``` Rules: - Timestamp is ISO-8601 with timezone (always UTC with `Z` suffix) - `run_id` comes from the run manifest (never generated by the agent) - No extra text on this line - This header enables run isolation and staleness detection per CLAUDE.md rule #12 ## 200-Line Hard Limit Per CLAUDE.md rule #11, context summaries MUST be under 200 lines. This is a hard limit, not a guideline. ### What Counts as a Line - Every line in the file, including blank lines, headers, and the `` comment - Code blocks count line-by-line - The revision history section (if present) counts toward the total ### When Approaching the Limit - Cut the least critical sections first (nice-to-have context, verbose explanations) - Replace inline details with references: `See full spec: docs/architecture/api/openapi/.yaml` - Consolidate related items into tables instead of bullet lists ## Content Structure A well-structured context summary follows this order: ```markdown # Summary ## Key Decisions - [Most impactful decisions with brief rationale] ## Output Artifacts - [List of files written with one-line descriptions] ## Cross-Cutting Concerns - [Tenant isolation approach taken] - [Auth/authz patterns applied] - [Observability hooks included] ## Dependencies & Assumptions - [What this agent assumed from upstream agents] - [Pending confirmations needed] ## Downstream Guidance - [What downstream agents need to know] - [Constraints imposed by this agent's decisions] ``` Not every section is needed for every agent. Omit sections that have no content rather than including empty headers. ## What to Include vs Reference ### Include Directly (in the summary) - Final decisions and their rationale (one sentence each) - Service names, package names, or entity names that downstream agents will reference - Tenant isolation strategy chosen for this agent's domain - Interface contracts that other agents depend on (method signatures, not full implementations) - Warnings or constraints that affect downstream work ### Reference from Full Output (do NOT inline) - Complete OpenAPI or AsyncAPI specs - Full SQL schema definitions - Detailed code examples longer than 10 lines - Exhaustive lists of endpoints, tables, or subjects - Implementation notes that only affect this agent's domain Use this format for references: ```markdown Full OpenAPI spec: `docs/architecture/api/openapi/.yaml` Tenant database provisioning: `docs/architecture/data/schemas/tenant-provisioning.sql` ``` ## Assumption Marking When an agent makes a decision in a domain it does NOT own (per CLAUDE.md rule #7), mark it explicitly: ```markdown Entity table uses UUID v7 primary keys with composite index on (tenant_id, entity_id). ``` ### Rules for Assumptions - Use the exact comment format: `` - Place the comment on the line immediately before the assumption text - Each assumption gets its own marker (do not batch multiple under one comment) - The owning agent, upon reading this summary, either confirms or overrides the assumption ## Early Draft Protocol Wave 2 agents run in parallel and may need each other's partial results. Agents that are upstream dependencies (like `database-architect` for `api-designer`) should publish an early draft. ### When to Publish an Early Draft - As soon as the agent has partial results that other same-wave agents can use - Before full analysis is complete - When the agent is an upstream dependency for another same-wave agent ### Draft Marking ```markdown # Database Architect Summary ## Key Decisions (partial) - Schema-per-tenant isolation with TenantRouter connection routing - Primary keys: UUID v7 for all tenant-scoped tables ## Pending Work - Index strategy not yet finalized - Migration ordering not yet determined ``` Rules: - Add `` on line 2 - Mark incomplete sections with `## ... (partial)` in the heading - Include a `## Pending Work` section listing what is not yet decided - When the final version is written, remove all `` markers and update the timestamp ## Revision History Protocol Per CLAUDE.md rule #9, agents MUST NOT overwrite context summaries without preserving history. ### On Re-Run When an agent runs again (retry or new iteration), append a revision history section: ```markdown ## Revision History ### Revision 2 -- 2026-03-09T16:00:00Z | Run: f47ac10b-... - **Changed**: Switched from application-level tenant filtering to schema-per-tenant isolation - **Reason**: Conflict resolution by architecture-lead (see decision-log entry) - **Affected sections**: Key Decisions, Downstream Guidance ### Revision 1 -- 2026-03-09T14:30:00Z | Run: f47ac10b-... - **Initial version** ``` ### Rules - Newest revision at the top - Each revision entry includes timestamp, run_id, what changed, and why - The `` header timestamp updates to the latest revision - The revision history counts toward the 200-line limit -- keep entries concise ## Examples ### GOOD ```markdown # Database Architect Summary ## Key Decisions - Schema-per-tenant isolation with TenantRouter connection routing to dedicated databases - UUID v7 primary keys for time-sortable inserts with reduced index fragmentation - Standard B-tree indexes per entity for common query patterns - JSONB for custom fields with GIN indexes per tenant ## Output Artifacts - `docs/architecture/data/schemas/core-tables.sql` -- core domain entity tables - `docs/architecture/data/schemas/tenant-provisioning.sql` -- Tenant database provisioning - `docs/architecture/data/schemas/indexes.sql` -- Index definitions ## Cross-Cutting Concerns - Each tenant gets a dedicated database; tables do NOT include tenant_id columns - Audit columns: `created_at`, `updated_at`, `created_by`, `updated_by` on all tables - Soft delete via `deleted_at TIMESTAMPTZ` (GDPR right-to-erasure uses hard delete) ## Dependencies & Assumptions DTOs map 1:1 to table columns for CRUD endpoints; custom projections for list endpoints. ## Downstream Guidance - All queries MUST use TenantRouter.GetPool(tenantID) to obtain the correct tenant database pool - Use `pkg/db.TenantRouter` helper (to be designed by sdk-designer) - Reference columns (`_id` suffix) hold entity IDs as plain UUID values — no FOREIGN KEY constraints exist. DAL resolves cross-entity references at runtime via batch queries. ``` ### BAD ```markdown # Database Summary We decided to use PostgreSQL with schema-per-tenant. Each tenant has its own schema. See the full schemas for details. ``` Why it is wrong: Missing `` header, no run_id, no structured sections, no assumption markers, no artifact references with paths, too vague for downstream agents to act on. ### BAD ```markdown # Database Architect Summary [... 250 lines of detailed SQL schemas inlined ...] ``` Why it is wrong: Exceeds the 200-line limit. Full schemas should be referenced, not inlined. Only key decisions and downstream-relevant constraints belong in the summary. ## Common Mistakes 1. **Omitting the `` header** -- Every context summary file must start with the ISO-8601 timestamp and run_id comment. Without it, run isolation (CLAUDE.md rule #12) and staleness detection break down. 2. **Inlining full specifications instead of referencing them** -- A 150-line OpenAPI excerpt leaves only 50 lines for actual summary content. Reference the full file path and include only the 3-5 most important endpoints or schemas. 3. **Silently overwriting on re-run without revision history** -- Per CLAUDE.md rule #9, previous content must be preserved via the `## Revision History` section. Overwriting without history makes it impossible to track what changed between iterations. 4. **Marking assumptions without naming the owning agent** -- Writing `` without specifying who should confirm it. Always use `` so the owner knows to review it. 5. **Publishing a draft without the DRAFT marker** -- If downstream agents read an incomplete summary and treat it as final, they build on unstable foundations. Always add `` on line 2 for partial results. 6. **Exceeding 200 lines and assuming "close enough" is acceptable** -- The 200-line limit is a hard constraint per CLAUDE.md rule #11, not a suggestion. Every line counts, including blanks and the revision history section.