{
  "id": "2026-04-26-reflection-stage-design-0e9ac2f474",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-26-reflection-stage-design.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.674Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Reflection Stage Design",
  "summary": "Reflection Stage Design Purpose Every project produces knowledge. Without a structured capture, that knowledge disappears when the session ends. The Reflection stage makes learning first class — agents reflect on what happened, Mindy synthesizes it, and the result writes permanently to BezelBrain. Every future project starts smarter. Lifecycle Position Refle...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Purpose",
      "level": 2,
      "body": "Every project produces knowledge. Without a structured capture, that knowledge disappears when the session ends. The Reflection stage makes learning first-class — agents reflect on what happened, Mindy synthesizes it, and the result writes permanently to BezelBrain. Every future project starts smarter.\n\n---"
    },
    {
      "title": "Lifecycle Position",
      "level": 2,
      "body": "```\nDesign → Plan → Build → Reflection → Launch\n```\n\nReflection is the fourth named stage in every project. Build does not close until Reflection completes. Launch does not open until Reflection closes.\n\n---"
    },
    {
      "title": "1. Phase Check-ins (during Build)",
      "level": 3,
      "body": "After each Build phase closes, every agent who worked that phase posts a short structured note as part of phase close. This is not a separate dispatch — it is the final step of closing a phase.\n\n**Format:** 3-5 lines per agent, structured around the five categories (see below). Included in the task `output_ref` — same mechanism as any other task output, no new infrastructure needed.\n\n**Owner:** Each agent. No orchestration needed.\n\n**Storage:** Mindy reads each `output_ref` as phases close and appends the check-in to the living project context document. These accumulate across all phases and become the source material for the project synthesis.\n\n---"
    },
    {
      "title": "2. Project Synthesis (the Reflection stage)",
      "level": 3,
      "body": "After Build completes, Mindy opens the Reflection stage. This is the full retrospective.\n\n**Flow:**\n\n```\nBuild completes\n  ↓\nMindy opens Reflection stage\n  ↓\nReflection tasks dispatched to all agents (parallel, depends_on: [])\n  ↓\nEach agent reads their phase check-ins, reflects across the full project,\nposts task.complete with output_ref\n  ↓\nSynthesis task fires (depends_on: [all reflection tasks])\nMindy reads every output_ref, synthesizes across five categories\n  ↓\nExec gate — Justin reviews synthesized document\nJustin may add his own perspective before it commits\n  ↓\nFinal document writes to BezelBrain + project HCS history topic\nReflection stage closes\n```\n\n---"
    },
    {
      "title": "The Five Categories",
      "level": 2,
      "body": "Every agent reflects across the same five categories. Mindy's synthesis organizes the final document around these.\n\n| # | Category | What it captures |\n|---|---|---|\n| 1 | **What we did well** | Patterns, decisions, and approaches to repeat |\n| 2 | **What we can improve** | Process gaps, communication failures, handoff friction |\n| 3 | **What would make us better** | Tools, integrations, workflow changes that would have helped |\n| 4 | **What we learned from mistakes** | Wrong decisions — wrong scope, wrong architecture, wrong interpretation |\n| 5 | **Errors and corrections** | Specific moments: tried X, it failed, Y was the correct approach |\n\nCategory 5 is the most concrete and the most valuable over time. It accumulates into a library of tried-and-failed paths with proven corrections — future agents load this and skip the mistake entirely.\n\n---"
    },
    {
      "title": "Agent Roles",
      "level": 2,
      "body": "All agents who participated in the project receive a reflection task. Tasks run in parallel.\n\n| Agent | Reflects on |\n|---|---|\n| Quinn | Code decisions, implementation errors, patterns found or missed |\n| Vikram | Architecture decisions, review findings, things caught late that should have been caught in Design |\n| Priya | Spec quality, missing acceptance criteria, gaps that caused Quinn to post blocked |\n| Zara | UX spec completeness, components that needed revision after Quinn started |\n| Luna | QA failures, acceptance criteria that were ambiguous or untestable |\n| Mindy | Project management — task graph accuracy, blocking events, plan changes, dispatch decisions |\n\n---"
    },
    {
      "title": "Synthesis Document Structure",
      "level": 2,
      "body": "Mindy produces one structured document per project:\n\n```\nProject: [name]\nDate: [ISO date]\nAgents: [list]\nPhases completed: [N]"
    },
    {
      "title": "What We Did Well",
      "level": 2,
      "body": "[synthesized across all agents]"
    },
    {
      "title": "What We Can Improve",
      "level": 2,
      "body": "[synthesized across all agents]"
    },
    {
      "title": "What Would Make Us Better",
      "level": 2,
      "body": "[tools, process, communication]"
    },
    {
      "title": "What We Learned From Mistakes",
      "level": 2,
      "body": "[synthesized across all agents]"
    },
    {
      "title": "Errors and Corrections",
      "level": 2,
      "body": "[specific pairs: tried X → Y was correct]\n```\n\n---"
    },
    {
      "title": "BezelBrain Write",
      "level": 2,
      "body": "One memory entry per project. Tagged with:\n- `project_id`\n- `project_name`\n- `date`\n- `agents_involved`\n- `type: reflection`\n\nFuture agents load this at session start. The error-correction pairs in Category 5 are also indexed separately for retrieval — an agent encountering a similar problem can pull the correction directly without loading the full reflection.\n\n---"
    },
    {
      "title": "Exec Gate",
      "level": 2,
      "body": "Justin reviews the synthesized document before it commits to BezelBrain. This serves two purposes:\n\n1. **Quality gate** — catch anything the synthesis missed or got wrong\n2. **Human perspective** — Justin can add observations that agents cannot see (strategic context, client feedback, external factors)\n\nJustin's additions are marked `author: justin` in the final document. The exec gate is the only point in Reflection where Justin is required. Everything else runs autonomously.\n\n---"
    },
    {
      "title": "Entity Model",
      "level": 2,
      "body": "```\nProject\n  └── Stage: Reflection\n        └── Phase: Agent Reflections (parallel)\n              └── Task: Quinn reflection\n              └── Task: Vikram reflection\n              └── Task: Priya reflection\n              └── Task: Zara reflection\n              └── Task: Luna reflection\n              └── Task: Mindy reflection\n        └── Phase: Synthesis (depends_on: all reflection tasks)\n              └── Task: Mindy synthesis → exec gate → BezelBrain write\n```\n\n---"
    },
    {
      "title": "What This Builds Over Time",
      "level": 2,
      "body": "Each project adds one reflection document to BezelBrain. Across ten projects:\n\n- Patterns that worked appear repeatedly — agents learn to default to them\n- Mistakes that recur get flagged — process changes before the third occurrence\n- The error-correction library grows — agents skip known failure paths\n- Tools and workflow gaps accumulate — platform improvements are evidence-based, not guessed\n\nThe system does not just run projects. It gets better at running projects."
    }
  ],
  "html_path": "artifacts/2026-04-26-reflection-stage-design-0e9ac2f474.html",
  "json_path": "artifacts/2026-04-26-reflection-stage-design-0e9ac2f474.json"
}