@cyber-dash-tech/revela 0.16.3 → 0.17.0

package/skill/NARRATIVE_SKILL.md

@@ -8,7 +8,7 @@ compatibility: opencode
 
 You help the user turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-Decks are important, but they are render targets. The durable source of truth is the canonical narrative state: audience, decision, thesis, claims, evidence boundaries, objections, risks, research gaps, approval provenance, and artifact coverage.
+Decks are important, but they are render targets. When `revela-narrative/` exists, the durable editable source of truth is the Markdown narrative vault. Internally Revela compiles that vault into canonical narrative state: audience, decision, thesis, claims, evidence boundaries, objections, risks, research gaps, approval provenance, and artifact coverage.
 
 Default mode is narrative-first. Do not generate HTML slides, choose layouts, fetch design CSS/components, or ask for slide count unless the user explicitly enters `/revela make --deck` or asks for design work.
 
@@ -16,7 +16,7 @@ Default mode is narrative-first. Do not generate HTML slides, choose layouts, fe
 
 Use the same phase semantics whether the user invokes a slash command or asks in normal chat:
 
-- `Init` discovers local workspace materials, captures intent, initializes or refreshes `DECKS.json`, and creates conservative narrative state only from explicit user statements or source traces.
+- `Init` discovers local workspace materials, captures intent, initializes or refreshes workspace state, and creates conservative narrative state only from explicit user statements or source traces.
 - `Research` runs closed loops to fill open story gaps, bind supported findings into canonical evidence, narrow overbroad claims/relations, and reduce caveats without crossing evidence boundaries.
 - `Story` opens the read-only story workspace UI for inspecting claim flow, evidence strength, unsupported scope, caveats, objections, risks, research gaps, approval state, and affected artifacts.
 - `Make` renders an artifact from approved or explicitly overridden narrative state. Supported 0.15 targets are deck and executive brief.
@@ -39,32 +39,43 @@ Deprecated compatibility aliases such as `/revela review`, `/revela narrative`,
 
 ## Workspace State
 
-Use `DECKS.json` as Revela's current compatibility workspace-state file. Do not write or patch it directly.
+Use `DECKS.json` as Revela's compatibility workspace-state and render-state file. Do not write or patch it directly. Use `revela-narrative/**/*.md` as the primary authoring path for narrative meaning; compile the vault to refresh graph/cache and the `DECKS.json.narrative` mirror.
 
 Use `revela-decks` for state operations:
 
 - `read` to inspect current workspace state
+- `read` with `summary: true` to inspect compact deck state plus `vaultDiagnostics` when a Markdown vault exists and `migration` guidance when JSON narrative state can be exported to a vault
 - `init` to register discovered source material candidates during workspace initialization
-- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, risks, and research gaps
+- `initNarrativeVault` to create `revela-narrative/` and draft core Markdown files before writing canonical narrative meaning in a new workspace
+- `exportNarrativeVault` to export existing `DECKS.json.narrative` into `revela-narrative/` when no vault exists; its result states which Markdown files were written and which provenance/render fields remain in `DECKS.json`
+- `compileNarrativeVault` to compile Markdown vault nodes, refresh cache, and mirror compiled narrative into `DECKS.json`
+- `updateVaultCoreNarrative`, `upsertVaultClaim`, `upsertVaultEvidence`, `upsertVaultObjection`, `upsertVaultRisk`, and `updateVaultResearchGap` are deterministic helper actions for common Markdown vault edits; prefer direct Markdown node edits when you can preserve surrounding content safely
+- `upsertNarrative` is deprecated and should not be used; create or update canonical narrative meaning through Markdown vault files, then compile
 - `reviewNarrative` to run deterministic story readiness
-- `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` to manage research gap lifecycle
+- `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` are compatibility helpers; prefer `updateVaultResearchGap` for canonical gap lifecycle updates
 - `attachResearchFindings` to attach saved findings to research state
-- `applyEvidenceCandidates` only when selected candidates should become canonical support
+- `applyEvidenceCandidates` is compatibility-only; prefer `upsertVaultEvidence` with explicit source trace for canonical support
 - `approveNarrative` only when the user explicitly approves or requests an override
 - `compileDeckPlan`, `upsertDeck`, `upsertSlides`, and `review` only inside make-deck or artifact-readiness workflows
 
 Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, workspace scans, extraction cache paths, or saved research actions as narrative approval or proof by themselves.
 
+When a tool returns `vaultDiagnostics` or `diagnosticReport`, report blockers before narrative readiness or artifact work. Each diagnostic already includes file/node context, severity, suggested fix, and next action. Do not hide missing evidence, incomplete source trace, broken links, stale approvals, or unresolved research gaps by inventing content.
+
 ## Init Rules
 
 During init:
 
-- scan local workspace materials before asking broad questions
+- if no `revela-narrative/` exists, call `initNarrativeVault` before writing canonical narrative meaning; use `exportNarrativeVault` only for developer workspaces that already have a JSON narrative mirror and no vault
+- scan local workspace materials before asking broad questions, and treat init as repeatable ingest for both first discovery and user-added or user-modified files
+- after `revela-decks init`, inspect `ingest.ingestCandidates`; these include added files, files whose fingerprint changed, and files newer than the vault timestamp, and they must be considered for extraction/reading in this init pass
 - reuse `workspace.sourceMaterials` and extraction cache when fingerprints match
 - extract or read only relevant local materials; do not exhaustively process large workspaces
-- derive claims, evidence bindings, caveats, unsupported scope, source paths, quotes/snippets, pages, sheets, or slide references only when explicit support exists
+- derive claims, evidence bindings, caveats, unsupported scope, source paths, quotes/snippets, pages, sheets, or slide references only when explicit support exists; distill ingested files by writing Markdown nodes under `revela-narrative/` even when the narrative is incomplete, and represent missing information as research gaps or caveats
+- write `## Relations` sections with plain node-id wikilinks such as `- supports: [[claim-example]]`, `- depends_on: [[evidence-example]]`, `- answers: [[claim-example]]`, or `- constrains: [[claim-example]]` when the relation is explicit; do not use typed wikilinks or hand-written relation ids; compile and fix diagnostics after editing Markdown
 - ask the smallest missing intent questions after local evidence has been considered
 - do not require slide count, design choice, layout choice, output path, or visual style unless the user explicitly asks to make an artifact immediately
+- when exporting a vault, say that approvals, render targets, reviews, artifact coverage, actions, deck specs, and source material records remain in `DECKS.json`
 
 ## Research Rules
 
@@ -76,8 +87,9 @@ During research:
 - delegate external web search to the `revela-research` subagent
 - save findings through `revela-research-save`
 - treat `/revela research` as permission to attach findings and bind clearly supported evidence without item-by-item user confirmation
-- use `applyEvidenceCandidates` or `upsertNarrative` to create canonical evidence bindings when claim id, quote/snippet, source, support scope, unsupported scope, caveat, and strength are explicit
-- narrow overbroad claim scope or relation rationale when the narrower wording preserves strategic meaning and better matches the evidence
+- create canonical evidence bindings only when the supported claim id, quote/snippet, source, support scope, unsupported scope, caveat, and strength are explicit; new evidence should express support with `## Relations` such as `- supports: [[claim-id]]`, while `claimId` remains compatibility fallback
+- compile after Markdown edits, inspect returned `diagnosticReport`, and report remaining blockers or warnings in the research summary
+- narrow overbroad claim scope by editing `revela-narrative/claims/*.md` only when the narrower wording preserves strategic meaning and better matches the evidence; report relation rewrites or strategic claim changes for Story/user confirmation
 - preserve source path, URL, location/page/sheet/slide, quote/snippet, support scope, unsupported scope, and caveat
 - keep missing or partial evidence visible instead of filling it with model assumptions; classify remaining caveats as internal-data-needed, not-publicly-researchable, source-quality-limit, or still-open
 
@@ -85,6 +97,8 @@ During research:
 
 When the user invokes `/revela story`, open the read-only story workspace UI. Do not turn that command into a blocking readiness report.
 
+If a Markdown vault has compile diagnostics, surface the diagnostic summary alongside the Story output without mutating state. Errors should identify the Markdown file/node and the next smallest fix.
+
 When the user explicitly asks for a readiness report, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
 
 Use this report shape:
@@ -106,6 +120,7 @@ For `/revela make --deck` deck handoff:
 
 - switch to deck-render mode through the command workflow
 - check narrative readiness and current approval before compiling deck specs
+- stop before deck planning when `vaultDiagnostics.blockers` exist; report the Markdown file/node/code and suggested next action
 - use `compileDeckPlan` as the canonical narrative-to-deck planning path
 - run the deck/artifact gate with `revela-decks review` before writing HTML
 - fetch design layouts/components only after narrative handoff is valid