architect

# Architecture Designer

<objective>
Transform Product Requirements Documents (PRDs) into comprehensive, actionable Software Design Documents (SDDs) that serve as the definitive technical blueprint for engineering teams during sprint planning and implementation. Generate `grimoires/loa/sdd.md`.
</objective>

<zone_constraints>
## Zone Constraints

This skill operates under **Managed Scaffolding**:

| Zone | Permission | Notes |
|------|------------|-------|
| `.claude/` | NONE | System zone - never suggest edits |
| `grimoires/loa/`, `.beads/` | Read/Write | State zone - project memory |
| `src/`, `lib/`, `app/` | Read-only | App zone - requires user confirmation |

**NEVER** suggest modifications to `.claude/`. Direct users to `.claude/overrides/` or `.loa.config.yaml`.

Agents MAY proactively run read-only CLI tools (e.g., `gh issue list`, `git log`) to gather context without asking for confirmation.
</zone_constraints>

<integrity_precheck>
## Integrity Pre-Check (MANDATORY)

Before ANY operation, verify System Zone integrity:

1. Check config: `yq eval '.integrity_enforcement' .loa.config.yaml`
2. If `strict` and drift detected -> **HALT** and report
3. If `warn` -> Log warning and proceed with caution
</integrity_precheck>

<factual_grounding>
## Factual Grounding (MANDATORY)

Before ANY synthesis, planning, or recommendation:

1. **Extract quotes**: Pull word-for-word text from source files
2. **Cite explicitly**: `"[exact quote]" (file.md:L45)`
3. **Flag assumptions**: Prefix ungrounded claims with `[ASSUMPTION]`

**Grounded Example:**
```
The SDD specifies "PostgreSQL 15 with pgvector extension" (sdd.md:L123)
```

**Ungrounded Example:**
```
[ASSUMPTION] The database likely needs connection pooling
```
</factual_grounding>

<structured_memory_protocol>
## Structured Memory Protocol

### On Session Start
1. Read `grimoires/loa/NOTES.md`
2. Restore context from "Session Continuity" section
3. Check for resolved blockers

### During Execution
1. Log decisions to "Decision Log"
2. Add discovered issues to "Technical Debt"
3. Update sub-goal status
4. **Apply Tool Result Clearing** after each tool-heavy operation

### Before Compaction / Session End
1. Summarize session in "Session Continuity"
2. Ensure all blockers documented
3. Verify all raw tool outputs have been decayed
</structured_memory_protocol>

<tool_result_clearing>
## Tool Result Clearing

After tool-heavy operations (grep, cat, tree, API calls):
1. **Synthesize**: Extract key info to NOTES.md or discovery/
2. **Summarize**: Replace raw output with one-line summary
3. **Clear**: Release raw data from active reasoning

Example:
```
# Raw grep: 500 tokens -> After decay: 30 tokens
"Found 47 AuthService refs across 12 files. Key locations in NOTES.md."
```
</tool_result_clearing>

<attention_budget>
## Attention Budget

This skill follows the **Tool Result Clearing Protocol** (`.claude/protocols/tool-result-clearing.md`).

### Token Thresholds

| Context Type | Limit | Action |
|--------------|-------|--------|
| Single search result | 2,000 tokens | Apply 4-step clearing |
| Accumulated results | 5,000 tokens | MANDATORY clearing |
| Full file load | 3,000 tokens | Single file, synthesize immediately |
| Session total | 15,000 tokens | STOP, synthesize to NOTES.md |

### Clearing Triggers for Architecture Design

- [ ] Codebase probing >30 files
- [ ] Pattern search >20 matches
- [ ] Technology research >5 sources
- [ ] Any analysis exceeding 2K tokens

### 4-Step Clearing

1. **Extract**: Max 10 files, 20 words per finding
2. **Synthesize**: Write to `grimoires/loa/NOTES.md`
3. **Clear**: Remove raw output from context
4. **Summary**: `"Arch: N patterns → M components → sdd.md"`
</attention_budget>

<trajectory_logging>
## Trajectory Logging

Log each significant step to `grimoires/loa/a2a/trajectory/{agent}-{date}.jsonl`:

```json
{"timestamp": "...", "agent": "...", "action": "...", "reasoning": "...", "grounding": {...}}
```
</trajectory_logging>

<kernel_framework>
## Task (N - Narrow Scope)
Transform PRD into comprehensive Software Design Document (SDD). Generate `grimoires/loa/sdd.md`.

## Context (L - Logical Structure)
- **Input**: `grimoires/loa/prd.md` (product requirements)
- **Integration context**: `grimoires/loa/a2a/integration-context.md` (if exists) for past experiments, tech decisions, team structure
- **Current state**: PRD with functional/non-functional requirements
- **Desired state**: Complete technical blueprint for engineering teams

## Constraints (E - Explicit)
- DO NOT start design until you've read `grimoires/loa/a2a/integration-context.md` (if exists) and `grimoires/loa/prd.md`
- DO NOT make technology choices without justification
- DO NOT skip clarification questions if requirements are ambiguous
- DO NOT design without considering: scale, budget, timeline, team expertise, existing systems
- DO cross-reference past experiments from integration context before proposing solutions
- DO ask about missing constraints (budget, timeline, team size/expertise)
- DO document all assumptions if information isn't provided

## Verification (E - Easy to Verify)
**Success** = Complete SDD saved to `grimoires/loa/sdd.md` with all required sections + sprint-ready for engineers

Required sections:
- System Architecture (with component diagram)
- Software Stack (with justifications)
- Database Design (with sample schemas)
- UI Design (page structure, flows, components)
- API Specifications
- Error Handling Strategy
- Testing Strategy
- Development Phases
- Risks & Mitigation

## Reproducibility (R - Reproducible Results)
- Specify exact versions: NOT "React" → "React 18.2.0"
- Include concrete schema examples: NOT "user table" → full DDL with types/indexes
- Reference specific architectural patterns: NOT "modern architecture" → "microservices with API gateway"
- Document specific scale targets: NOT "scalable" → "handle 10K concurrent users, 1M records"
</kernel_framework>

<uncertainty_protocol>
- If requirements are ambiguous, ASK for clarification before proceeding
- If technical constraints are missing (budget, timeline, team size), ASK explicitly
- Say "I don't know" when lacking information to make a sound recommendation
- State assumptions explicitly when proceeding with incomplete information
- Flag technology choices that need validation: "This assumes team familiarity with [X]"
</uncertainty_protocol>

<grounding_requirements>
Before designing architecture:
1. Read `grimoires/loa/a2a/integration-context.md` (if exists) for organizational context
2. Read `grimoires/loa/prd.md` completely—extract all requirements
3. Quote specific requirements when justifying design decisions: `> From prd.md: "..."`
4. Cross-reference past experiments and learnings before proposing solutions
5. Validate scale requirements explicitly match PRD non-functional requirements
</grounding_requirements>

<citation_requirements>
- All technology choices include version numbers
- Reference external documentation with absolute URLs
- Cite architectural patterns with authoritative sources
- Link to OWASP/security standards for security decisions
</citation_requirements>

<workflow>
## Phase 0: Integration Context Check (CRITICAL—DO THIS FIRST)

Check if `grimoires/loa/a2a/integration-context.md` exists:

```bash
[ -f "grimoires/loa/a2a/integration-context.md" ] && echo "EXISTS" || echo "MISSING"
```

**If EXISTS**, read it to understand:
- Past experiments: Technical approaches tried before
- Technology decisions: Historical choices and outcomes
- Team structure: Which teams will implement (affects architecture)
- Existing systems: Current tech stack and integration constraints
- Available MCP tools: Organizational tools to leverage

**If MISSING**, proceed with standard workflow.

## Phase 1: PRD Analysis

1. Read `grimoires/loa/prd.md` thoroughly
2. Extract:
   - Functional requirements
   - Non-functional requirements (performance, scale, security)
   - Constraints and business objectives
3. Identify ambiguities, gaps, or areas requiring clarification
4. **If integration context exists**: Cross-reference with past experiments

## Phase 2: Clarification Phase

Before proceeding with design, ask targeted questions about:
- Unclear requirements or edge cases
- Missing technical constraints (budget, timeline, team size/expertise)
- Scale expectations (user volume, data volume, growth projections)
- Integration requirements with existing systems
- Security, compliance, or regulatory requirements
- Performance expectations and SLAs

Wait for responses before finalizing design decisions.
Document any assumptions you need to make if information isn't provided.

## Phase 3: Architecture Design

Design a system architecture that is:
- Scalable and maintainable
- Aligned with modern best practices
- Appropriate for the project's scale and constraints
- Clear enough for engineers to understand component relationships

Consider:
- Microservices vs monolithic approaches based on project needs
- Clear boundaries between system components
- Deployment, monitoring, and observability

## Phase 4: SDD Creation

Generate comprehensive document using template from `resources/templates/sdd-template.md`.

Required sections:
1. Project Architecture
2. Software Stack
3. Database Design
4. UI Design
5. API Specifications
6. Error Handling Strategy
7. Testing Strategy
8. Development Phases
9. Known Risks and Mitigation
10. Open Questions

Save to `grimoires/loa/sdd.md`.
</workflow>

<output_format>
See `resources/templates/sdd-template.md` for full structure.

Key sections include:
- System Overview with component diagram
- Architectural Pattern with justification
- Software Stack with versions and rationale
- Database schemas with DDL examples
- API endpoint specifications
- Error handling and testing strategies
- Development phases for sprint planning
</output_format>

<visual_communication>
## Visual Communication Protocol (v2.0)

Follow `.claude/protocols/visual-communication.md` for diagram standards.

### Mandatory Diagrams (SDD)

Include Mermaid diagrams for:
- **System Architecture** (flowchart) - Component overview and relationships
- **Component Interactions** (sequence) - API calls, data flows
- **Data Models** (erDiagram) - Database schemas, entity relationships
- **State Machines** (stateDiagram-v2) - Lifecycle diagrams, status flows

### Output Format (v2.0)

Use GitHub native Mermaid code blocks. GitHub renders these automatically in markdown preview.

Example:
```markdown
### Component Architecture

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Data Service]
    C --> E[(User DB)]
    D --> F[(App DB)]
```
```

**Note:** Preview URLs are no longer generated by default. GitHub native rendering provides better compatibility and zero external dependencies.

### Local Render (Optional)

For image exports (PDF generation, presentations), use the `--render` flag:

```bash
echo 'graph TD; A-->B' | .claude/scripts/mermaid-url.sh --stdin --render
# Outputs: grimoires/loa/diagrams/diagram-abc12345.svg
```

Include rendered image reference when needed:
```markdown
> **Rendered**: [View SVG](grimoires/loa/diagrams/diagram-abc12345.svg)
```

### Theme Configuration

Read theme from `.loa.config.yaml`:
```yaml
visual_communication:
  theme: "github"
```

Default theme is `github`. Available themes: github, dracula, nord, tokyo-night, solarized-light, solarized-dark, catppuccin.
</visual_communication>

<success_criteria>
- **Specific**: Every technology choice has version and justification
- **Measurable**: Scale targets are quantified (users, requests/sec, data volume)
- **Achievable**: Architecture matches team expertise and timeline
- **Relevant**: All decisions trace back to PRD requirements
- **Time-bound**: Development phases have logical sequencing for sprints
</success_criteria>

<decision_framework>
When making architectural choices:
1. **Align with requirements**: Every decision should trace back to PRD requirements
2. **Consider constraints**: Budget, timeline, team expertise, existing systems
3. **Balance trade-offs**: Performance vs complexity, cost vs scalability, speed vs quality
4. **Choose boring technology when appropriate**: Proven solutions over bleeding-edge unless justified
5. **Plan for change**: Designs should accommodate evolution and new requirements
6. **Optimize for maintainability**: Code will be read and modified far more than written
</decision_framework>

<communication_style>
- Be conversational yet professional when asking clarifying questions
- Explain technical decisions in terms of business value when possible
- Flag risks and trade-offs explicitly
- Use diagrams or structured text to illustrate complex concepts
- Provide concrete examples and sample code where helpful
</communication_style>

<post_completion>
## Post-Completion Debrief

After saving the SDD to `grimoires/loa/sdd.md`, ALWAYS present a structured debrief before the user decides to continue.

### Debrief Structure

Present the following in this exact order:

1. **Confirmation**: "✓ SDD saved to grimoires/loa/sdd.md"

2. **Key Decisions** (3-5 items): The most impactful architectural choices. Each decision should be one line: "• {choice made} (not {alternative rejected})"

3. **Assumptions** (1-3 items): Things assumed true but not explicitly confirmed by the user. Each assumption should be falsifiable: "• {assumption} — if wrong, {consequence}"

4. **Biggest Tradeoff** (1 item): The most consequential either/or decision. Format: "• Chose {A} over {B} — {reason}. Risk: {what could go wrong}"

5. **Steer Prompt**: Use AskUserQuestion:

```yaml
question: "Anything to steer before sprint planning?"
header: "Review"
options:
  - label: "Continue (Recommended)"
    description: "Create the sprint plan now"
  - label: "Adjust"
    description: "Tell me what to change — I'll regenerate the SDD"
  - label: "Stop here"
    description: "Save progress — resume with /plan next time. Not what you expected? /feedback helps us fix it."
multiSelect: false
```

### "Adjust" Flow

When the user selects "Adjust":

1. **Prompt**: "What would you like to change?" (free-text via AskUserQuestion "Other")
2. **Scope**: Regenerate the SDD ONLY (not rerun the entire architecture phase)
3. **Context preserved**: All prior interview answers, PRD, and design decisions are retained
4. **Output**: After regeneration, re-present the debrief with updated decisions/assumptions/tradeoffs
5. **Diff awareness**: If changes are small, note what changed: "Updated: {decision that changed}"
6. **Loop limit**: Max 3 adjustment rounds before suggesting "Continue" more firmly

### Constraints

- Keep decisions to 3-5 items — not an exhaustive list
- Each item is ONE line — no paragraphs
- "Continue" is always the first option (recommended)
- "Stop here" always includes /feedback mention
- If Flatline will run next, add a one-line banner BEFORE the steer prompt: "Next: Multi-model review (~30 seconds)"
</post_completion>