>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588804. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The migrate-site system has demonstrably been able to self-diagnose structural problems and design fixes during sessions &mdash; but these insights were always triggered by user prompting or written as session-specific notes that never fed back into the skill. The clearest example: after a Ralph Loop session consumed 2.4&times; the expected tokens, the next morning's session designed a Phase 3.5 QA loop to prevent the same over-reliance on visual iteration. This inter-session self-diagnosis is the prototype for a formal Phase 9.</p> <p>The corpus also documents a session that ran for thousands of records, produced significant lessons, and updated zero memory or skill files. Memory file <code>memory/project_events_migration.md</code> was read at L10548 but never updated; no CLAUDE.md updates observed; no skill file updates observed. Lessons exist only in the narrative; they do not propagate to future runs.</p> <p>A dedicated Phase 9 makes this retrospective a first-class part of every migration run. After <code>migration_completed</code> is logged (and before the session closes), the orchestrator runs a structured retrospective: what failed, what took longer than expected, what was re-discovered that was already in the gotchas file, what new gotcha should be added. The output is a <code>lessons.md</code> file with concrete skill change proposals for the next run. This creates a compounding improvement loop: each migration makes the skill slightly better for the next one.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run a long migrate-site session.</li> <li>Observe that lessons (re-discovered gotchas, slow phases, retry storms) are mentioned in the narrative but never written to a persistent file.</li> <li>Run a second migration. Observe the same gotchas and slow phases recur &mdash; the previous run's lessons did not transfer.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Add Phase 9 to <code>migrate-site/SKILL.md</code>.</strong> Phase 9 runs after Phase 8 (visual review gate) and before session close:</p> <pre>## Phase 9: Post-Migration Retrospective After migration_completed is logged, run the orchestrator retrospective: 1. Read state.jsonl &mdash; count failed dispatches, retries, compaction events 2. Read timing.jsonl &mdash; identify phases that took &gt;2&times; their Phase 1 estimate 3. Read docs/migration/issues/ &mdash; count issues filed vs. closed; flag any unclosed 4. Cross-reference all gotcha-class failures against docs/migration/gotchas.md 5. Write docs/migration/lessons.md with: (a) what failed and why, (b) new gotchas, (c) proposed skill changes 6. If new gotchas found: append to docs/migration/gotchas.md 7. Produce Phase 9 gate checklist in docs/migration/workflow/9-retrospective-checklist.json</pre><p><strong>Step 2 &mdash; Create a <code>lessons.md</code> template</strong> with sections: "What failed", "Retry storms", "New gotchas (add to gotchas.md)", "Proposed skill changes for next run".</p> <p><strong>Step 3 &mdash; Seed <code>docs/migration/gotchas.md</code></strong> with the known gotchas (per Sprint 1 1-07):</p> <ul> <li><code>canvas:upload</code> takes one <code>-c</code> flag per invocation (not multiple <code>-c</code> flags in one call).</li> <li><code>getNodePath()</code> returns truthy <code>'#'</code> when <code>path.alias</code> is null and <code>drupal_internal__nid</code> is absent &mdash; always check <code>path !== '#'</code>.</li> <li><code>FormattedText</code> is SSR-only &mdash; use <code>dangerouslySetInnerHTML</code> for client-side body rendering.</li> <li>Mercury theme: all <code>md:</code> Tailwind utilities need <code>!important</code> mirrors in <code>global.css</code>.</li> <li>ToolSearch must be re-run after every compaction to reload deferred tool schemas.</li> </ul> <p><strong>Step 4 &mdash; Mandatory orchestrator instruction.</strong> "Before closing the session, run Phase 9 even if <code>migration_completed</code> was declared. The retrospective takes 5&ndash;10 minutes and produces compounding value across all future runs."</p> <p><strong>Why this works.</strong> Self-diagnosis succeeds because the migration artifacts (<code>state.jsonl</code>, <code>timing.jsonl</code>, <code>token-usage.jsonl</code>, issue files, compaction summaries) already contain enough signal to identify what went wrong. The system writes this data &mdash; it just never reads it back in a structured retrospective. Phase 9 is not creative; it systematically reads the session's own artifacts and maps anomalies to skill improvement opportunities.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add Phase 9 section to <code>migrate-site/SKILL.md</code>.</li> <li>Create <code>docs/migration/lessons.md</code> template.</li> <li>Create or update <code>docs/migration/gotchas.md</code> seed with the known gotchas above.</li> <li>Decide: orchestrator-run step or dispatched <code>retrospective-agent.md</code>? Recommend orchestrator-run (Phase 9 is a synthesis task that benefits from full context).</li> <li>Verify: after a migration, <code>docs/migration/lessons.md</code> exists with at least one entry per section, <code>workflow/9-retrospective-checklist.json</code> shows <code>overall: pass</code>, new gotchas appear in <code>gotchas.md</code> with the session timestamp.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New artifacts: <code>docs/migration/lessons.md</code>, <code>docs/migration/workflow/9-retrospective-checklist.json</code>. Phase 9 also appends to existing <code>docs/migration/gotchas.md</code>.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-8-Patterns-To-Encode/04-NEW-4-self-aware-retrospective-phase.md</code> (id: NEW-4)</li> <li>Pattern origin: <code>RESEARCH-2026-04-28/04-efi-ed/f6a58b2b-deep-dive.md</code> (Ralph Loop 2.4&times; blow-up that triggered next-morning Phase 3.5 design)</li> <li>Pattern definition: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P12 (Phase 3.5 QA Loop) and &sect; P16 (memory-driven feedback persistence)</li> <li>Q4 post-mortem (lost-lessons evidence): <code>RESEARCH-2026-04-28/03-efi-ed-source/Q4-records-8651-to-11536/post-mortem-learnings.md</code></li> <li>Encoding recommendation: <code>RESEARCH-2026-04-28/99-final/NEW-things-to-try.md</code> &sect; 10 (Persistent Session State)</li> <li>Related bug: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P1-4 (compaction knowledge loss &mdash; gotchas.md is the fix)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Phase 9 as agent or orchestrator step? Recommend orchestrator-run, not a dispatched subagent &mdash; Phase 9 is fundamentally synthesis.</li> <li><code>lessons.md</code> &rarr; skill update pipeline: who applies the proposed changes? Recommend (a) Phase 9 produces proposals, user decides.</li> <li>Timing: should Phase 9 run before or after the user reviews the visual gaps report (Phase 8 output)? Recommend after &mdash; the user's response itself may produce lessons.</li> </ul>