Synthesis & Validation

This framework has two parts: a Sprint Synthesis Framework that prevents context burn by distilling sprint outputs into living documents, and a Validation Framework that ensures every piece of work meets a consistent quality bar.

Part A: Sprint Synthesis

Distill, Don't Repeat

The raw artifacts of a sprint — meeting notes, Slack threads, Figma explorations, code spikes, user testing recordings — are inputs, not outputs. The output is the synthesized knowledge captured in three canonical artifacts.

If you find yourself re-reading raw sprint material to answer a question, the synthesis has failed.

Every project suffers from context burn — the gradual loss of institutional knowledge as raw artifacts pile up. A team that finishes a sprint with 47 documents, 12 recordings, and 200 Slack messages has not created knowledge. They have created noise. The cost is concrete: onboarding slows down, decisions can't be traced, AI assistants can't consume sprawling histories, and sprint planning starts from scratch.

The test: Can someone who missed the entire sprint read only the three living documents and be fully caught up? If the answer is no, the synthesis is incomplete. If yes, the raw artifacts can be archived.

Anti-patterns to avoid:

• The Archive Trap — saving everything "just in case" without synthesizing
• The Summary Email — writing a summary but not updating the canonical documents
• The Fresh Start — beginning each sprint from scratch instead of building on living documents

The Three Artifacts

1. DECISIONS.md

The canonical record of every significant decision made during the project.

Template:

# Decisions Log

## DEC-[NNN]: [Decision Title]

**Date**: YYYY-MM-DD
**Sprint**: [Sprint number or name]
**Status**: Accepted | Superseded by DEC-[NNN] | Reverted

### Context
[1-2 paragraphs explaining why this decision was needed.]

### Decision
[Clear, unambiguous statement of what was decided.]

### Alternatives Considered
1. **[Alternative A]**: [Brief description]
   - Pros: [Why this was attractive]
   - Cons: [Why this was rejected]

### Consequences
- [Expected positive outcomes]
- [Expected negative outcomes or trade-offs]

### Dissent
[Record any dissenting opinions. If none, state "None recorded."]

### Review Trigger
[Conditions under which this decision should be revisited.]

Rules:

• Decisions are append-only. Never delete a decision — supersede it.
• Every decision must record alternatives considered.
• The dissent field is mandatory. "None recorded" is acceptable; blank is not.

2. PERSONAS.md

The canonical record of the team's understanding of its users.

Template:

# Personas

## Persona: [Descriptive Name]

**Role**: [Job title, function, or user type]
**Last Updated**: YYYY-MM-DD
**Confidence**: High | Medium | Low
**Source**: [Sprint N user testing | Stakeholder interview | Domain research]

### Goal
[Primary objective when using the system. One sentence.]

### Context
[Environment, constraints, tools, frequency of interaction.]

### Pain Points
- [Frustration 1]
- [Frustration 2]

### Success Metric
[How this persona measures whether the system helped them.]

### Open Questions
- [Things we still do not know about this persona]

Rules:

• Personas are refined over time, not rewritten. Update the date and adjust confidence as new information arrives.
• "High" = validated through user research. "Medium" = stakeholder input. "Low" = assumptions.
• Open questions drive future research. No open questions means the team has stopped learning.

3. PRINCIPLES.md

The canonical record of design and engineering principles validated through project work.

Template:

# Design & Engineering Principles

## PRIN-[NNN]: [Principle Name]

**Status**: Proposed | Validated | Retired
**Source**: [Sprint N retrospective | User testing | Technical discovery]

### Statement
[The principle in one clear sentence.]

### Rationale
[Why this principle matters. What failure mode does it prevent?]

### Example
[A concrete example of the principle applied correctly.]

### Counter-Example
[What happens when this principle is violated.]

Rules:

• New principles start as "Proposed" and are promoted to "Validated" after confirmation through sprint work.
• Retired principles are kept with a note explaining why.
• The counter-example field is mandatory — a principle without one is too abstract.

Sprint Synthesis Workflow

At the end of every sprint (or at natural breakpoints):

1. Gather raw material — collect all sprint artifacts
2. Extract decisions — add each to DECISIONS.md
3. Update personas — incorporate new insights, adjust confidence
4. Validate principles — promote confirmed principles, retire disproven ones
5. Archive raw material — it has served its purpose
6. Run the context burn test — can someone who missed the sprint catch up from the living documents alone?

Part B: Validation Framework

The Four Pillars

Every piece of delivered work — a design, a prototype, a feature — must be validated against four pillars.

Apply these at design review, PR review, QA, and retrospectives.

Validation Checklist

## Validation: [Feature/Component Name]

### Clarity
- [ ] Purpose is immediately obvious without explanation
- [ ] All states are explicitly handled (loading, empty, error, success)
- [ ] Primary action is visually dominant
- [ ] Labels and microcopy are unambiguous

### Attribution
- [ ] Data sources are visible or accessible
- [ ] Timestamps show data freshness
- [ ] AI-generated content is labeled as such
- [ ] Calculations can be verified by the user

### Reversibility
- [ ] Destructive actions require confirmation
- [ ] Undo is available for common actions
- [ ] Soft delete is used where appropriate
- [ ] Navigation does not lose unsaved work

### Consistency
- [ ] Visual patterns match the design system
- [ ] Interaction patterns match similar features
- [ ] Terminology matches the glossary
- [ ] Error handling follows the established format

Implementation Guide

Step 1: Initialize Artifacts

Create DECISIONS.md, PERSONAS.md, and PRINCIPLES.md at the project root using the templates above. Populate with whatever is known, even if confidence is low. Mark initial entries as "Pre-Sprint" or "Assumed."

Step 2: Establish the Synthesis Ritual

Allocate dedicated time (2-4 hours) at the end of every sprint for synthesis. Without a protected time block, synthesis will be deferred indefinitely and context burn will set in.

Step 3: Integrate Validation into Workflow

Add the four-pillar checklist to your PR template. During design reviews, ground critique in the pillars ("the primary action fails the clarity check") rather than subjective feedback ("I don't like the layout").

The PAGE-TREE Pattern

The PAGE-TREE is a structural map of every page and state in the application. It prevents duplicate work and ensures complete coverage.

# PAGE-TREE

## /dashboard
- **Purpose**: Primary landing page after login
- **States**: Loading, Empty (new user), Populated, Error
- **Key Components**: MetricCards, ActivityFeed, QuickActions
- **Journey**: Onboarding (step 3), Core Workflow (step 1)
- **Status**: Implemented | In Progress | Planned

Each entry maps a route to its purpose, states, components, journey connections, and implementation status. Update whenever pages are added or changed.

PR Validation Checklist

Every pull request must pass this checklist before merge:

## PR Validation

### Four Pillars
- [ ] **Clarity**: UI purpose and state are immediately obvious
- [ ] **Attribution**: All data can be traced to its source
- [ ] **Reversibility**: All actions can be undone (or are gated)
- [ ] **Consistency**: Patterns match established conventions

### Technical
- [ ] Tests pass (`npm test`)
- [ ] Build succeeds (`npm run build`)
- [ ] No lint errors (`npm run lint`)
- [ ] Accessibility audit passes
- [ ] Responsive behavior verified (mobile, tablet, desktop)

### Documentation
- [ ] DECISIONS.md updated (if a decision was made)
- [ ] PERSONAS.md updated (if user understanding changed)
- [ ] PRINCIPLES.md updated (if a principle was validated or discovered)
- [ ] PAGE-TREE updated (if pages were added or changed)
- [ ] CLAUDE.md updated (if a new correction was needed)