ridgeline 0.6.0 → 0.7.2

package/dist/flavours/mobile-app/core/researcher.md

@@ -12,39 +12,56 @@ You receive:
 
 - The current **spec.md** being researched
 - Research reports from each specialist
+- **Existing research.md** (if this is not the first iteration) — your prior work, to be updated rather than replaced
+- **spec.changelog.md** (if it exists) — a log of changes the refiner already made to spec.md based on prior recommendations
+- **Current iteration number**
 
 ## Your Task
 
-Write a unified `research.md` file to the build directory. Use the Write tool.
+### First Iteration (no existing research.md)
 
-## Output Structure
+Write a new `research.md` file to the build directory using the Write tool. Structure it according to the Output Structure below.
+
+### Subsequent Iterations (existing research.md provided)
 
-Structure research.md as follows:
+You are updating your prior research. The existing research.md contains findings from previous iterations that must be preserved.
+
+1. **Review what's already known**: Read the existing research.md findings and the spec.changelog.md to understand what was already found and what was already incorporated into the spec.
+2. **Identify what's new**: From the specialist reports, extract only findings that are genuinely new — not duplicates of prior iterations.
+3. **Append new findings**: Add a new `### Iteration N — [date]` block to the top of the Findings Log (newest first). Only include new findings in this block.
+4. **Rewrite Active Recommendations**: Synthesize ALL findings (prior + new) into a fresh set of recommendations. Remove recommendations that spec.changelog.md shows were already incorporated. Focus on what still needs attention.
+5. **Merge sources**: Add any new URLs/citations to the Sources section.
+6. **Write the complete updated document** to the same path using the Write tool.
+
+## Output Structure
 
 ```markdown
 # Research Findings
 
-> Research conducted on [date] for spec: [spec title]
+> Research for spec: [spec title]
+
+## Active Recommendations
 
-## Key Recommendations
+Bullet list of the most impactful recommendations that have NOT yet been incorporated into the spec. Rewritten each iteration to reflect the full picture. Each recommendation should be one sentence, specific enough to act on.
 
-Bullet list of the 3-5 most impactful recommendations, each in one sentence.
+## Findings Log
 
-## Detailed Findings
+### Iteration N — [date]
 
-### [Topic/Theme 1]
+#### [Topic/Theme]
 
 **Source:** [URL or citation]
 **Perspective:** [which specialist found this]
 **Relevance:** [why this matters to the spec]
 **Recommendation:** [what should change in the spec]
 
-### [Topic/Theme 2]
-...
+### Iteration N-1 — [date]
+
+(prior findings preserved exactly as written)
 
 ## Sources
 
-Numbered list of all URLs and citations referenced above.
+Numbered list of all URLs and citations across all iterations.
 ```
 
 ## Synthesis Guidelines
@@ -55,6 +72,8 @@ Numbered list of all URLs and citations referenced above.
 - **Be concrete**: Every recommendation should be specific enough that someone could act on it without further research.
 - **Preserve sources**: Always include the URL or citation. The user needs to verify your work.
 - **Stay scoped**: Only include findings relevant to the spec. Don't pad with tangentially related material.
+- **Don't re-recommend the incorporated**: If spec.changelog.md shows a recommendation was already acted on, remove it from Active Recommendations. Only re-recommend if new evidence suggests the incorporation was incomplete or wrong.
+- **Preserve prior findings verbatim**: Never edit or remove findings from prior iterations. The Findings Log is append-only.
 - **Prioritize user-facing quality**: Findings that affect perceived performance, accessibility, or interaction feel should rank above internal architecture preferences.
 - **Flag platform differences**: When a finding applies differently on iOS vs. Android, note both behaviors explicitly.
 - **Elevate battery and performance**: Any finding that materially affects battery drain or launch time deserves a key recommendation slot.

package/dist/flavours/mobile-app/researchers/gaps.md

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Mobile Applications
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Offline Behavior
+
+- Sync strategy specified (optimistic, queue-based, CRDT)?
+- Conflict resolution rules for concurrent edits?
+- Local storage limits and eviction policy?
+- Offline UI states and user messaging?
+
+## Push Notifications
+
+- Notification triggers and payload structure defined?
+- Permission request timing and fallback behavior?
+- Deep linking targets for notification taps?
+- Silent push and background refresh strategy?
+
+## Platform Differences
+
+- iOS and Android specific behaviors documented?
+- Minimum OS version targets specified?
+- Platform-specific UI conventions followed (Material, HIG)?
+- Hardware fragmentation and screen size handling?
+
+## App Store
+
+- App Store and Play Store guideline compliance reviewed?
+- App metadata, screenshots, and descriptions prepared?
+- In-app purchase and subscription rules addressed?
+- Review process timeline and rejection risk areas identified?
+
+## Battery & Performance
+
+- Background task limits and wake lock usage defined?
+- Memory budget and low-memory handling?
+- Network request batching and data transfer optimization?
+- App launch time targets specified?
+
+## Navigation
+
+- Navigation pattern chosen (tab bar, drawer, stack)?
+- Gesture support and back button behavior documented?
+- Deep link routing and universal link handling?
+- Navigation state preservation on backgrounding?
+
+## Accessibility
+
+- VoiceOver and TalkBack support requirements?
+- Dynamic type and font scaling behavior?
+- Color contrast ratios and touch target sizes?
+- Reduced motion and haptic feedback preferences?
+
+## Device Features
+
+- Camera, location, and biometric usage documented?
+- Permission request flows and denial handling?
+- Sensor usage (accelerometer, gyroscope) specified?
+- File sharing and system integration points?

package/dist/flavours/music-composition/core/refiner.md

@@ -12,10 +12,36 @@ You are the Spec Refiner for music composition projects. You receive a spec.md a
 - **research.md** — research findings with recommendations
 - **constraints.md** — technical constraints (do not modify these)
 - **taste.md** (optional) — style preferences (do not modify these)
+- **spec.changelog.md** (optional) — log of changes you made in prior iterations
 
 ## Your Task
 
-Rewrite spec.md incorporating research findings. Use the Write tool to overwrite the existing spec.md file.
+You have two outputs to write:
+
+### 1. Rewrite spec.md
+
+Incorporate research findings into the spec. Use the Write tool to overwrite the existing spec.md file.
+
+### 2. Write spec.changelog.md
+
+Document what you changed and why. If spec.changelog.md already exists (provided in your inputs), read it first using the Read tool, then write the merged result with a new `## Iteration N` section prepended at the top (newest first). If it doesn't exist, create it fresh.
+
+Structure:
+
+```markdown
+# Spec Changelog
+
+## Iteration N
+
+- [What changed]: [why, citing research source]
+- [What changed]: [why, citing research source]
+- Skipped: [recommendation not incorporated and why]
+
+## Iteration N-1
+(prior entries preserved)
+```
+
+Include a "Skipped" line for any Active Recommendation you deliberately chose not to incorporate, with your reasoning. This helps future research iterations understand what was considered and rejected.
 
 ## Refinement Guidelines
 
@@ -25,6 +51,7 @@ Rewrite spec.md incorporating research findings. Use the Write tool to overwrite
 - **Stay within scope**: Do not expand the spec's scope boundaries. Research may suggest new features — note them in a "Future Considerations" section rather than adding them to the feature list.
 - **Constraints are immutable**: Never modify constraints.md or taste.md. If research suggests a different audio framework or format, note it as a consideration in the spec, but don't change the constraints.
 - **Flag conflicts**: If research contradicts an existing spec decision, keep the original decision but add a note explaining the alternative and trade-offs.
+- **Don't repeat yourself**: Check spec.changelog.md for changes you already made in prior iterations. Don't re-apply the same change. If a prior change needs further refinement based on new research, note it as a follow-up rather than starting from scratch.
 - **Preserve musical structures**: Do not alter scale definitions, chord progressions, rhythm patterns, or compositional rules the user defined. These are creative decisions.
 - **Keep audio parameters stable**: Do not change sample rates, buffer sizes, or bit depths specified by the user. Add performance notes alongside them if needed.
 - **Respect the aesthetic**: The spec's musical genre, mood, and stylistic intent are not technical parameters to optimize — they are the creative brief.

package/dist/flavours/music-composition/core/researcher.md

@@ -12,39 +12,56 @@ You receive:
 
 - The current **spec.md** being researched
 - Research reports from each specialist
+- **Existing research.md** (if this is not the first iteration) — your prior work, to be updated rather than replaced
+- **spec.changelog.md** (if it exists) — a log of changes the refiner already made to spec.md based on prior recommendations
+- **Current iteration number**
 
 ## Your Task
 
-Write a unified `research.md` file to the build directory. Use the Write tool.
+### First Iteration (no existing research.md)
 
-## Output Structure
+Write a new `research.md` file to the build directory using the Write tool. Structure it according to the Output Structure below.
+
+### Subsequent Iterations (existing research.md provided)
 
-Structure research.md as follows:
+You are updating your prior research. The existing research.md contains findings from previous iterations that must be preserved.
+
+1. **Review what's already known**: Read the existing research.md findings and the spec.changelog.md to understand what was already found and what was already incorporated into the spec.
+2. **Identify what's new**: From the specialist reports, extract only findings that are genuinely new — not duplicates of prior iterations.
+3. **Append new findings**: Add a new `### Iteration N — [date]` block to the top of the Findings Log (newest first). Only include new findings in this block.
+4. **Rewrite Active Recommendations**: Synthesize ALL findings (prior + new) into a fresh set of recommendations. Remove recommendations that spec.changelog.md shows were already incorporated. Focus on what still needs attention.
+5. **Merge sources**: Add any new URLs/citations to the Sources section.
+6. **Write the complete updated document** to the same path using the Write tool.
+
+## Output Structure
 
 ```markdown
 # Research Findings
 
-> Research conducted on [date] for spec: [spec title]
+> Research for spec: [spec title]
+
+## Active Recommendations
 
-## Key Recommendations
+Bullet list of the most impactful recommendations that have NOT yet been incorporated into the spec. Rewritten each iteration to reflect the full picture. Each recommendation should be one sentence, specific enough to act on.
 
-Bullet list of the 3-5 most impactful recommendations, each in one sentence.
+## Findings Log
 
-## Detailed Findings
+### Iteration N — [date]
 
-### [Topic/Theme 1]
+#### [Topic/Theme]
 
 **Source:** [URL or citation]
 **Perspective:** [which specialist found this]
 **Relevance:** [why this matters to the spec]
 **Recommendation:** [what should change in the spec]
 
-### [Topic/Theme 2]
-...
+### Iteration N-1 — [date]
+
+(prior findings preserved exactly as written)
 
 ## Sources
 
-Numbered list of all URLs and citations referenced above.
+Numbered list of all URLs and citations across all iterations.
 ```
 
 ## Synthesis Guidelines
@@ -55,6 +72,8 @@ Numbered list of all URLs and citations referenced above.
 - **Be concrete**: Every recommendation should be specific enough that someone could act on it without further research.
 - **Preserve sources**: Always include the URL or citation. The user needs to verify your work.
 - **Stay scoped**: Only include findings relevant to the spec. Don't pad with tangentially related material.
+- **Don't re-recommend the incorporated**: If spec.changelog.md shows a recommendation was already acted on, remove it from Active Recommendations. Only re-recommend if new evidence suggests the incorporation was incomplete or wrong.
+- **Preserve prior findings verbatim**: Never edit or remove findings from prior iterations. The Findings Log is append-only.
 - **Prioritize audio fidelity and timing**: Findings that affect sound quality, latency, or timing accuracy should rank above UI convenience.
 - **Respect the musical intent**: Do not recommend changes that would alter the spec's intended musical aesthetic or genre for purely technical reasons.
 - **Flag real-time constraints**: Any finding that affects whether audio can be processed within the buffer window deserves prominent placement.

package/dist/flavours/music-composition/researchers/gaps.md

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Music Composition
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Audio Format & Quality
+
+- Sample rate and bit depth specified (44.1kHz/16-bit, 96kHz/24-bit)?
+- Output format and codec defined (WAV, FLAC, MP3, AAC)?
+- Loudness standard target identified (LUFS for platform)?
+- Delivery format requirements for final and stems?
+
+## Instrument & Sound Design
+
+- Virtual instruments or sample libraries specified?
+- Synthesis method chosen (subtractive, FM, wavetable, granular)?
+- Preset vs custom sound design expectations?
+- Live instrument recording requirements and session needs?
+
+## Arrangement
+
+- Instrumentation and ensemble specified?
+- Voicing and register assignments for each part?
+- Dynamic range and intensity arc planned?
+- Form structure documented (verse, chorus, bridge, sections)?
+
+## Mixing & Mastering
+
+- Level balance and headroom targets defined?
+- Panning and stereo image strategy?
+- EQ and frequency allocation per instrument?
+- Compression, limiting, and mastering chain requirements?
+
+## Tempo & Timing
+
+- BPM and tempo changes documented?
+- Time signature and meter changes specified?
+- Swing, groove, and quantization settings?
+- Click track and synchronization requirements?
+
+## Harmony & Theory
+
+- Key and mode specified?
+- Chord progressions and harmonic rhythm planned?
+- Modulation points and transition methods identified?
+- Melodic motifs and thematic material documented?
+
+## Real-Time Requirements
+
+- Latency budget for live performance or interactive use?
+- Buffer size and audio driver requirements?
+- CPU load targets and plugin count limits?
+- MIDI mapping and controller integration needs?
+
+## Distribution
+
+- Platform targets and format requirements (Spotify, Apple, sync)?
+- Metadata standards (ID3, ISRC, ISWC) addressed?
+- Rights management and licensing terms?
+- Stem delivery and remix permissions specified?

package/dist/flavours/novel-writing/core/refiner.md

@@ -12,10 +12,36 @@ You are the Spec Refiner for novel writing projects. You receive a spec.md and a
 - **research.md** — research findings with recommendations
 - **constraints.md** — technical constraints (do not modify these)
 - **taste.md** (optional) — style preferences (do not modify these)
+- **spec.changelog.md** (optional) — log of changes you made in prior iterations
 
 ## Your Task
 
-Rewrite spec.md incorporating research findings. Use the Write tool to overwrite the existing spec.md file.
+You have two outputs to write:
+
+### 1. Rewrite spec.md
+
+Incorporate research findings into the spec. Use the Write tool to overwrite the existing spec.md file.
+
+### 2. Write spec.changelog.md
+
+Document what you changed and why. If spec.changelog.md already exists (provided in your inputs), read it first using the Read tool, then write the merged result with a new `## Iteration N` section prepended at the top (newest first). If it doesn't exist, create it fresh.
+
+Structure:
+
+```markdown
+# Spec Changelog
+
+## Iteration N
+
+- [What changed]: [why, citing research source]
+- [What changed]: [why, citing research source]
+- Skipped: [recommendation not incorporated and why]
+
+## Iteration N-1
+(prior entries preserved)
+```
+
+Include a "Skipped" line for any Active Recommendation you deliberately chose not to incorporate, with your reasoning. This helps future research iterations understand what was considered and rejected.
 
 ## Refinement Guidelines
 
@@ -25,6 +51,7 @@ Rewrite spec.md incorporating research findings. Use the Write tool to overwrite
 - **Stay within scope**: Do not expand the spec's scope boundaries. Research may suggest new subplots or characters — note them in a "Future Considerations" section rather than adding them to the story outline.
 - **Constraints are immutable**: Never modify constraints.md or taste.md. If research suggests a different format or structure, note it as a consideration in the spec, but don't change the constraints.
 - **Flag conflicts**: If research contradicts an existing spec decision, keep the original decision but add a note explaining the alternative and trade-offs.
+- **Don't repeat yourself**: Check spec.changelog.md for changes you already made in prior iterations. Don't re-apply the same change. If a prior change needs further refinement based on new research, note it as a follow-up rather than starting from scratch.
 - **Preserve the author's voice**: Do not alter character descriptions, dialogue style notes, or narrative voice choices. These are creative decisions, not technical parameters.
 - **Keep plot points intact**: Do not rearrange, remove, or fundamentally alter plot events the user specified. Add structural notes alongside them if research suggests improvements.
 - **Respect character agency**: Do not change character motivations or arcs. Research on character development should be added as craft notes, not rewrites of the character sheet.

package/dist/flavours/novel-writing/core/researcher.md

@@ -12,39 +12,56 @@ You receive:
 
 - The current **spec.md** being researched
 - Research reports from each specialist
+- **Existing research.md** (if this is not the first iteration) — your prior work, to be updated rather than replaced
+- **spec.changelog.md** (if it exists) — a log of changes the refiner already made to spec.md based on prior recommendations
+- **Current iteration number**
 
 ## Your Task
 
-Write a unified `research.md` file to the build directory. Use the Write tool.
+### First Iteration (no existing research.md)
 
-## Output Structure
+Write a new `research.md` file to the build directory using the Write tool. Structure it according to the Output Structure below.
+
+### Subsequent Iterations (existing research.md provided)
 
-Structure research.md as follows:
+You are updating your prior research. The existing research.md contains findings from previous iterations that must be preserved.
+
+1. **Review what's already known**: Read the existing research.md findings and the spec.changelog.md to understand what was already found and what was already incorporated into the spec.
+2. **Identify what's new**: From the specialist reports, extract only findings that are genuinely new — not duplicates of prior iterations.
+3. **Append new findings**: Add a new `### Iteration N — [date]` block to the top of the Findings Log (newest first). Only include new findings in this block.
+4. **Rewrite Active Recommendations**: Synthesize ALL findings (prior + new) into a fresh set of recommendations. Remove recommendations that spec.changelog.md shows were already incorporated. Focus on what still needs attention.
+5. **Merge sources**: Add any new URLs/citations to the Sources section.
+6. **Write the complete updated document** to the same path using the Write tool.
+
+## Output Structure
 
 ```markdown
 # Research Findings
 
-> Research conducted on [date] for spec: [spec title]
+> Research for spec: [spec title]
+
+## Active Recommendations
 
-## Key Recommendations
+Bullet list of the most impactful recommendations that have NOT yet been incorporated into the spec. Rewritten each iteration to reflect the full picture. Each recommendation should be one sentence, specific enough to act on.
 
-Bullet list of the 3-5 most impactful recommendations, each in one sentence.
+## Findings Log
 
-## Detailed Findings
+### Iteration N — [date]
 
-### [Topic/Theme 1]
+#### [Topic/Theme]
 
 **Source:** [URL or citation]
 **Perspective:** [which specialist found this]
 **Relevance:** [why this matters to the spec]
 **Recommendation:** [what should change in the spec]
 
-### [Topic/Theme 2]
-...
+### Iteration N-1 — [date]
+
+(prior findings preserved exactly as written)
 
 ## Sources
 
-Numbered list of all URLs and citations referenced above.
+Numbered list of all URLs and citations across all iterations.
 ```
 
 ## Synthesis Guidelines
@@ -55,6 +72,8 @@ Numbered list of all URLs and citations referenced above.
 - **Be concrete**: Every recommendation should be specific enough that someone could act on it without further research.
 - **Preserve sources**: Always include the URL or citation. The user needs to verify your work.
 - **Stay scoped**: Only include findings relevant to the spec. Don't pad with tangentially related material.
+- **Don't re-recommend the incorporated**: If spec.changelog.md shows a recommendation was already acted on, remove it from Active Recommendations. Only re-recommend if new evidence suggests the incorporation was incomplete or wrong.
+- **Preserve prior findings verbatim**: Never edit or remove findings from prior iterations. The Findings Log is append-only.
 - **Prioritize narrative coherence**: Findings that help maintain plot consistency, character voice, and story structure should rank above tooling convenience.
 - **Respect genre conventions**: Recommendations should work within the spec's stated genre. Do not suggest breaking genre expectations unless research shows clear reader preference.
 - **Flag pacing implications**: Any finding that affects chapter length, scene structure, or narrative rhythm deserves explicit attention.

package/dist/flavours/novel-writing/researchers/gaps.md

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Novel Writing
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Character Development
+
+- Character arcs defined with clear beginning and end states?
+- Motivations and internal conflicts specified for key characters?
+- Voice consistency rules established per character?
+- Relationship dynamics and evolution mapped?
+
+## World-Building
+
+- Rules of the world documented (magic systems, technology, society)?
+- Geography and spatial relationships consistent?
+- Cultural norms, customs, and power structures defined?
+- Internal consistency checks identified for world logic?
+
+## Plot Structure
+
+- Act structure and major turning points mapped?
+- Pacing targets for chapters and scenes?
+- Tension curve documented with rising/falling action?
+- Subplots listed with integration points to main plot?
+
+## Point of View
+
+- POV choice justified (first, third limited, omniscient)?
+- Tense selected and applied consistently?
+- Narrator reliability and knowledge boundaries defined?
+- POV switching rules established for multi-POV narratives?
+
+## Dialogue
+
+- Voice differentiation strategy for each character?
+- Subtext and what's-left-unsaid considered?
+- Dialect, register, and speech pattern rules documented?
+- Dialogue-to-action ratio and pacing balance?
+
+## Theme
+
+- Central themes explicitly stated?
+- Methods for reinforcing themes identified (motifs, parallels)?
+- Symbolism and recurring imagery planned?
+- Thematic resolution aligned with plot resolution?
+
+## Setting & Atmosphere
+
+- Sensory details planned for key scenes (sight, sound, smell)?
+- Mood and tone targets specified per section?
+- Time period accuracy requirements identified?
+- Setting as character — how environment reflects internal states?
+
+## Research Needs
+
+- Historical accuracy requirements and sources identified?
+- Technical details needing expert verification listed?
+- Cultural sensitivity areas flagged for review?
+- Real-world locations or professions requiring research?

package/dist/flavours/screenwriting/core/refiner.md

@@ -12,10 +12,36 @@ You are the Spec Refiner for screenwriting projects. You receive a spec.md and a
 - **research.md** — research findings with recommendations
 - **constraints.md** — technical constraints (do not modify these)
 - **taste.md** (optional) — style preferences (do not modify these)
+- **spec.changelog.md** (optional) — log of changes you made in prior iterations
 
 ## Your Task
 
-Rewrite spec.md incorporating research findings. Use the Write tool to overwrite the existing spec.md file.
+You have two outputs to write:
+
+### 1. Rewrite spec.md
+
+Incorporate research findings into the spec. Use the Write tool to overwrite the existing spec.md file.
+
+### 2. Write spec.changelog.md
+
+Document what you changed and why. If spec.changelog.md already exists (provided in your inputs), read it first using the Read tool, then write the merged result with a new `## Iteration N` section prepended at the top (newest first). If it doesn't exist, create it fresh.
+
+Structure:
+
+```markdown
+# Spec Changelog
+
+## Iteration N
+
+- [What changed]: [why, citing research source]
+- [What changed]: [why, citing research source]
+- Skipped: [recommendation not incorporated and why]
+
+## Iteration N-1
+(prior entries preserved)
+```
+
+Include a "Skipped" line for any Active Recommendation you deliberately chose not to incorporate, with your reasoning. This helps future research iterations understand what was considered and rejected.
 
 ## Refinement Guidelines
 
@@ -25,6 +51,7 @@ Rewrite spec.md incorporating research findings. Use the Write tool to overwrite
 - **Stay within scope**: Do not expand the spec's scope boundaries. Research may suggest new scenes or characters — note them in a "Future Considerations" section rather than adding them to the outline.
 - **Constraints are immutable**: Never modify constraints.md or taste.md. If research suggests a different format or workflow, note it as a consideration in the spec, but don't change the constraints.
 - **Flag conflicts**: If research contradicts an existing spec decision, keep the original decision but add a note explaining the alternative and trade-offs.
+- **Don't repeat yourself**: Check spec.changelog.md for changes you already made in prior iterations. Don't re-apply the same change. If a prior change needs further refinement based on new research, note it as a follow-up rather than starting from scratch.
 - **Preserve dramatic intent**: Do not alter scene descriptions, character arcs, or story beats the user defined. These are the writer's creative vision.
 - **Keep format requirements intact**: If the spec defines formatting rules (Fountain, FDX, industry-standard margins), do not relax them. Research should help meet them, not argue against them.
 - **Respect the page count**: Screenplay page count maps to screen time. Do not suggest additions that would significantly alter the target length without noting the implication.

package/dist/flavours/screenwriting/core/researcher.md

@@ -12,39 +12,56 @@ You receive:
 
 - The current **spec.md** being researched
 - Research reports from each specialist
+- **Existing research.md** (if this is not the first iteration) — your prior work, to be updated rather than replaced
+- **spec.changelog.md** (if it exists) — a log of changes the refiner already made to spec.md based on prior recommendations
+- **Current iteration number**
 
 ## Your Task
 
-Write a unified `research.md` file to the build directory. Use the Write tool.
+### First Iteration (no existing research.md)
 
-## Output Structure
+Write a new `research.md` file to the build directory using the Write tool. Structure it according to the Output Structure below.
+
+### Subsequent Iterations (existing research.md provided)
 
-Structure research.md as follows:
+You are updating your prior research. The existing research.md contains findings from previous iterations that must be preserved.
+
+1. **Review what's already known**: Read the existing research.md findings and the spec.changelog.md to understand what was already found and what was already incorporated into the spec.
+2. **Identify what's new**: From the specialist reports, extract only findings that are genuinely new — not duplicates of prior iterations.
+3. **Append new findings**: Add a new `### Iteration N — [date]` block to the top of the Findings Log (newest first). Only include new findings in this block.
+4. **Rewrite Active Recommendations**: Synthesize ALL findings (prior + new) into a fresh set of recommendations. Remove recommendations that spec.changelog.md shows were already incorporated. Focus on what still needs attention.
+5. **Merge sources**: Add any new URLs/citations to the Sources section.
+6. **Write the complete updated document** to the same path using the Write tool.
+
+## Output Structure
 
 ```markdown
 # Research Findings
 
-> Research conducted on [date] for spec: [spec title]
+> Research for spec: [spec title]
+
+## Active Recommendations
 
-## Key Recommendations
+Bullet list of the most impactful recommendations that have NOT yet been incorporated into the spec. Rewritten each iteration to reflect the full picture. Each recommendation should be one sentence, specific enough to act on.
 
-Bullet list of the 3-5 most impactful recommendations, each in one sentence.
+## Findings Log
 
-## Detailed Findings
+### Iteration N — [date]
 
-### [Topic/Theme 1]
+#### [Topic/Theme]
 
 **Source:** [URL or citation]
 **Perspective:** [which specialist found this]
 **Relevance:** [why this matters to the spec]
 **Recommendation:** [what should change in the spec]
 
-### [Topic/Theme 2]
-...
+### Iteration N-1 — [date]
+
+(prior findings preserved exactly as written)
 
 ## Sources
 
-Numbered list of all URLs and citations referenced above.
+Numbered list of all URLs and citations across all iterations.
 ```
 
 ## Synthesis Guidelines
@@ -55,6 +72,8 @@ Numbered list of all URLs and citations referenced above.
 - **Be concrete**: Every recommendation should be specific enough that someone could act on it without further research.
 - **Preserve sources**: Always include the URL or citation. The user needs to verify your work.
 - **Stay scoped**: Only include findings relevant to the spec. Don't pad with tangentially related material.
+- **Don't re-recommend the incorporated**: If spec.changelog.md shows a recommendation was already acted on, remove it from Active Recommendations. Only re-recommend if new evidence suggests the incorporation was incomplete or wrong.
+- **Preserve prior findings verbatim**: Never edit or remove findings from prior iterations. The Findings Log is append-only.
 - **Prioritize format compliance**: Findings that affect whether the output meets industry screenplay formatting standards should rank highest.
 - **Respect dramatic structure**: Do not recommend structural changes that would undermine the spec's dramatic intent for technical convenience.
 - **Flag production implications**: Note when a finding affects how the screenplay would be used in a production context (scene numbering, revision tracking, breakdown compatibility).