context-summary-writing

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 m

SKILL.md

GitHub

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/ <agent-name>-summary.md
Detailed Design docs/detailed-design/context/ <agent-name>-summary.md

Review agents (Wave 3/4) do NOT write context summaries. They write to their respective reviews/ directories but still use the <!-- Generated --> header.

Required Header

Every context summary MUST start with this exact comment format on line 1:

<!-- Generated: 2026-03-09T14:30:00Z | Run: f47ac10b-58cc-4372-a567-0e02b2c3d479 -->

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 <!-- Generated --> 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/<service-name>.yaml
  • Consolidate related items into tables instead of bullet lists

Content Structure

A well-structured context summary follows this order:

<!-- Generated: 2026-03-09T14:30:00Z | Run: f47ac10b-... -->
# <Agent Name> 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:

Full <service-name> OpenAPI spec: `docs/architecture/api/openapi/<service-name>.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:

<!-- ASSUMPTION -- pending database-architect confirmation -->
Entity table uses UUID v7 primary keys with composite index on (tenant_id, entity_id).

Rules for Assumptions

  • Use the exact comment format: <!-- ASSUMPTION -- pending <owner-agent> confirmation -->
  • 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

<!-- Generated: 2026-03-09T13:00:00Z | Run: f47ac10b-... -->
<!-- DRAFT -- will be updated -->
# 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

<!-- DRAFT sections will be replaced in the final version -->

Rules:

  • Add <!-- DRAFT -- will be updated --> 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 <!-- DRAFT --> 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:

## 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 <!-- Generated --> header timestamp updates to the latest revision
  • The revision history counts toward the 200-line limit -- keep entries concise

Examples

GOOD

<!-- Generated: 2026-03-09T14:30:00Z | Run: f47ac10b-58cc-4372-a567-0e02b2c3d479 -->
# 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
<!-- ASSUMPTION -- pending api-designer confirmation -->
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

# 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 <!-- Generated --> header, no run_id, no structured sections, no assumption markers, no artifact references with paths, too vague for downstream agents to act on.

BAD

<!-- Generated: 2026-03-09T14:30:00Z | Run: f47ac10b-... -->
# 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 <!-- Generated --> 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 <!-- ASSUMPTION --> without specifying who should confirm it. Always use <!-- ASSUMPTION -- pending <agent-name> confirmation --> 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 <!-- DRAFT -- will be updated --> 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.