Imported from PremModhaOfficial/NFR-pipeline (skills/context-summary-writing/SKILL.md). Install upstream with npx skills add PremModhaOfficial/NFR-pipeline --skill context-summary-writing. Copyright stays with the author.

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

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.