ridgeline 0.6.0 → 0.7.2

package/dist/flavours/screenwriting/researchers/gaps.md

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Screenwriting
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Format & Structure
+
+- Act breaks and sequence structure defined?
+- Scene heading conventions consistent (INT/EXT, location, time)?
+- Page count targets specified for format (feature, pilot, short)?
+- Cold open, teaser, or tag requirements?
+
+## Visual Storytelling
+
+- Show-don't-tell opportunities identified in exposition-heavy scenes?
+- Action line style and visual specificity calibrated?
+- Visual motifs and recurring imagery planned?
+- Montage and transition techniques specified where needed?
+
+## Character
+
+- Casting considerations noted (age range, ensemble balance)?
+- Dialogue voice distinct and consistent per character?
+- Character introductions written with visual specificity?
+- Character wants vs needs clearly differentiated?
+
+## Pacing
+
+- Scene length variation planned for rhythm?
+- Tonal shifts mapped and motivated?
+- Act momentum building toward climax?
+- Breathing room between high-intensity sequences?
+
+## Production Feasibility
+
+- Location count and variety assessed for budget?
+- VFX and practical effects needs identified?
+- Cast size and day-player requirements estimated?
+- Budget tier and production scale realistic for the story?
+
+## Genre Conventions
+
+- Audience expectations for the genre understood?
+- Genre beats present and properly sequenced?
+- Tone consistency maintained or shifts justified?
+- Subversion of conventions intentional and effective?
+
+## Dialogue
+
+- Subtext present — characters rarely say exactly what they mean?
+- Naturalism balanced with dramatic purpose?
+- Exposition handled organically, not through info-dumps?
+- Dialogue rhythm and interruption patterns varied?
+
+## Market & Industry
+
+- Target audience and demographic clearly defined?
+- Distribution format specified (theatrical, streaming, broadcast)?
+- Comparable titles identified for positioning?
+- Series potential or franchise considerations addressed?

package/dist/flavours/security-audit/core/refiner.md

@@ -12,10 +12,36 @@ You are the Spec Refiner for security audit projects. You receive a spec.md and
 - **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 audit areas — note them in a "Future Considerations" section rather than adding them to the audit scope.
 - **Constraints are immutable**: Never modify constraints.md or taste.md. If research suggests different tooling, 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 security trade-off.
+- **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.
 - **Severity drives priority**: When incorporating findings, place critical and high-severity items prominently. Do not bury them in general recommendations.
 - **Preserve the threat model**: Do not alter the spec's defined threat model, trust boundaries, or asset classifications. Add findings within the existing model's framework.
 - **Keep remediation actionable**: When research suggests fixes, ensure they are specific to the spec's technology stack, not generic security advice.

package/dist/flavours/security-audit/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, especially CVE IDs. 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.
 - **Include CVE references**: When a finding relates to a known vulnerability, always include the CVE identifier.
 - **Flag exploitability**: Note whether a vulnerability is theoretical or has known exploits in the wild.
 - **Assess blast radius**: For each finding, indicate what data or functionality would be compromised if exploited.

package/dist/flavours/security-audit/researchers/gaps.md

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Security Audit
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Attack Surface
+
+- Network exposure and open ports enumerated?
+- API surface and public endpoints catalogued?
+- Input vectors identified (forms, file uploads, query params)?
+- Third-party integrations and trust boundaries mapped?
+
+## Authentication & Authorization
+
+- Auth flow documented (OAuth, SAML, MFA)?
+- Session management and token lifecycle specified?
+- Privilege escalation paths reviewed?
+- Role-based or attribute-based access control defined?
+
+## Data Protection
+
+- Encryption at rest and in transit specified (algorithms, key length)?
+- Key management and rotation policy documented?
+- PII inventory and classification completed?
+- Data masking and redaction rules for logs and exports?
+
+## Vulnerability Classes
+
+- Injection risks assessed (SQL, command, LDAP, template)?
+- XSS prevention strategy (CSP, output encoding)?
+- CSRF and SSRF protections in place?
+- Deserialization and file upload risks addressed?
+
+## Infrastructure
+
+- Cloud configuration hardened (IAM, security groups, buckets)?
+- Container security (base images, scanning, runtime policies)?
+- Secrets management (vault, rotation, no hardcoded secrets)?
+- Network segmentation and firewall rules reviewed?
+
+## Compliance
+
+- Regulatory requirements identified (SOC 2, PCI-DSS, GDPR)?
+- Audit logging coverage and retention specified?
+- Data residency and sovereignty requirements met?
+- Penetration testing schedule and scope defined?
+
+## Incident Response
+
+- Detection and alerting mechanisms in place?
+- Incident classification and severity levels defined?
+- Runbook and escalation procedures documented?
+- Recovery procedures and RTO/RPO targets specified?
+
+## Supply Chain
+
+- Dependency audit completed (known vulnerabilities)?
+- Software bill of materials (SBOM) generated?
+- Update and patching policy documented?
+- Version pinning and lock file enforcement?

package/dist/flavours/software-engineering/core/builder.md

@@ -32,6 +32,8 @@ Do not implement work belonging to other phases. Do not add features not in your
 
 Verify your work after making changes. If a check command is specified in constraints.md, run it. If specialist agents are available, use the **verifier** agent — it can intelligently verify your work even when no check command exists.
 
+If this phase produces user-facing UI, capture screenshots to verify the visual output matches expectations. Run a visual diff against reference images if they exist.
+
 - If checks pass, continue.
 - If checks fail, fix the failures. Then check again.
 - Do not skip verification. Do not ignore failures. Do not proceed with broken checks.

package/dist/flavours/software-engineering/core/refiner.md

@@ -12,10 +12,36 @@ You are the Spec Refiner for software engineering projects. You receive a spec.m
 - **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 framework or language, 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.
 - **Emphasize behaviors and outcomes**: Frame additions in terms of what the system should do and what users should experience, not how to implement it.
 - **Preserve API contracts**: Do not alter endpoint definitions, data schemas, or interface contracts the user defined. Add edge case notes alongside them.
 - **Keep error handling intent**: Do not change the spec's error handling strategy. Add research-backed edge cases within the existing error model.

package/dist/flavours/software-engineering/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.
 - **Emphasize behaviors over implementations**: Recommendations should focus on what the system should do and why, not prescribe specific code patterns.
 - **Flag complexity trade-offs**: When a recommendation adds architectural complexity, explicitly note what it costs in addition to what it buys.
 - **Highlight testability**: Findings that affect how easily the system can be tested deserve prominent placement.

package/dist/flavours/software-engineering/core/reviewer.md

@@ -33,6 +33,8 @@ Only read files when a specific acceptance criterion or constraint requires insp
 
 If specialist agents are available, use the **verifier** agent to run verification against the changed code. This provides structured check results beyond what manual inspection alone catches. If a check command exists in constraints.md, the verifier will run it along with any other relevant verification.
 
+If the phase includes user-facing changes, capture screenshots to verify the visual output. Check for obvious layout issues, broken styling, or visual regressions.
+
 Delegate mechanical checks to the verifier: compilation, test pass/fail, artifact existence, command output. Do not duplicate this work manually.
 
 If the verifier reports failures, the phase fails. Analyze the failures and include them in your verdict.

package/dist/flavours/software-engineering/flavour.json

@@ -0,0 +1,7 @@
+{
+  "name": "software-engineering",
+  "recommendedSkills": [
+    "agent-browser",
+    "visual-diff"
+  ]
+}

package/dist/flavours/software-engineering/researchers/gaps.md

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Software Engineering
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Architecture
+
+- System boundaries and service decomposition defined?
+- Communication patterns specified (sync, async, event-driven)?
+- Data flow and ownership between services documented?
+- Technology selection justified with trade-off analysis?
+
+## API Design
+
+- Versioning strategy specified (URL, header, query param)?
+- Pagination, filtering, and sorting patterns defined?
+- Error codes and response format standardized?
+- Rate limiting and throttling policy documented?
+
+## Database
+
+- Schema design and entity relationships documented?
+- Indexing strategy aligned with query patterns?
+- Migration plan and tooling specified?
+- Backup frequency and recovery time objectives?
+
+## CI/CD
+
+- Pipeline stages and quality gates defined?
+- Test coverage thresholds and required checks?
+- Deployment strategy specified (blue-green, canary, rolling)?
+- Rollback procedure and criteria documented?
+
+## Observability
+
+- Logging strategy (structured, levels, retention policy)?
+- Metrics and dashboards for key business and system health?
+- Distributed tracing for cross-service requests?
+- Alerting thresholds and escalation procedures?
+
+## Security
+
+- Authentication and authorization model specified?
+- Input validation boundaries and sanitization rules?
+- Secrets management and rotation policy?
+- Dependency scanning and vulnerability patching cadence?
+
+## Scalability
+
+- Bottleneck identification and load testing plan?
+- Caching strategy and invalidation rules?
+- Horizontal and vertical scaling approach documented?
+- Resource budgets and auto-scaling triggers defined?
+
+## Developer Experience
+
+- Local development setup documented and reproducible?
+- API and architecture documentation current?
+- Onboarding guide for new contributors?
+- Code review standards and contribution guidelines?

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

@@ -12,10 +12,36 @@ You are the Spec Refiner for technical writing 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 documentation sections — note them in a "Future Considerations" section rather than adding them to the content plan.
 - **Constraints are immutable**: Never modify constraints.md or taste.md. If research suggests a different documentation framework, 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 content hierarchy**: Do not reorganize the spec's defined information architecture. Add notes about alternative structures alongside the existing one.
 - **Keep audience definitions stable**: Do not change who the documentation is written for. Research may reveal additional audiences — note them without altering the primary target.
 - **Respect the style guide**: If the spec references a style guide or voice/tone guidelines, do not contradict them with research-based suggestions.

package/dist/flavours/technical-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 findability**: Findings that help readers locate the right content faster should rank above aesthetic improvements.
 - **Emphasize accuracy over style**: For technical docs, correct information outranks polished prose. Flag any findings about technical accuracy.
 - **Note maintenance burden**: Highlight findings that affect how easily the documentation can be kept up to date as the underlying product evolves.

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

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Technical Writing
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Audience
+
+- Target skill level and experience defined?
+- Prerequisites and assumed knowledge listed?
+- Reader personas documented with goals and pain points?
+- Multiple audience segments addressed with appropriate paths?
+
+## Structure
+
+- Information architecture and content hierarchy planned?
+- Navigation strategy specified (sidebar, breadcrumbs, search)?
+- Progressive disclosure applied to complex topics?
+- Landing pages and entry points designed for each audience?
+
+## Content Types
+
+- Tutorial vs reference vs how-to distinction applied?
+- Content type chosen appropriately for each topic?
+- Conceptual overviews provided before procedural steps?
+- Troubleshooting and FAQ sections included where needed?
+
+## Code Examples
+
+- Language and framework versions specified?
+- Examples runnable and independently testable?
+- Copy-friendly formatting with syntax highlighting?
+- Error handling and edge cases shown, not just happy path?
+
+## Visuals
+
+- Diagrams used for architecture and data flow?
+- Screenshots annotated and versioned with the product?
+- Alt text provided for all images and diagrams?
+- Visual style consistent across the documentation?
+
+## Search & Discovery
+
+- SEO metadata and page titles optimized?
+- Internal cross-linking between related topics?
+- Search index coverage verified?
+- Canonical URLs and redirect strategy for moved content?
+
+## Maintenance
+
+- Update triggers identified (release, API change, deprecation)?
+- Content ownership and review cadence assigned?
+- Deprecation and sunset process for outdated content?
+- Version-specific documentation strategy (versioned docs, banners)?
+
+## Accessibility
+
+- Reading level appropriate for the audience?
+- Screen reader compatibility verified?
+- Color contrast and font sizing meet WCAG standards?
+- Keyboard navigation supported for interactive elements?