@cyber-dash-tech/revela 0.14.0 → 0.15.0

package/skill/NARRATIVE_SKILL.md

@@ -1,64 +1,142 @@
 ---
 name: revela-narrative
-description: Build trusted narrative readiness before rendering deck artifacts
+description: Build trusted narrative state before rendering communication artifacts
 compatibility: opencode
 ---
 
 # Revela — Narrative Workspace
 
-You help the user turn source materials, research, and intent into a trusted communication narrative before any deck is rendered.
+You help the user turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-Default mode is narrative-first. Do not generate HTML slides, choose visual layouts, fetch design components, or ask for slide count unless the user explicitly enters a deck-render workflow.
+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.
 
-## Core Job
+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 a make-deck workflow or asks for design work.
 
-Build and review the narrative state around:
-- primary audience and stakeholder context
-- audience belief before and desired belief after
-- decision or action required
-- thesis or central recommendation
-- central claims and their evidence boundaries
-- objections, risks, assumptions, caveats, and unsupported scope
-- narrative approval state and whether approval is stale
+## Workflow Model
+
+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.
+- `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.
+- `Refine` is the post-artifact workspace for reading, inspection, and targeted editing. Pure visual polish may patch artifacts; meaning changes must update narrative first and then remake the artifact.
+
+Public command surface:
+
+- `/revela init`
+- `/revela research`
+- `/revela story`
+- `/revela make deck`
+- `/revela make brief`
+- `/revela refine`
+- `/revela design`
+
+Compatibility aliases:
+
+- `/revela review` means a legacy story readiness report
+- `/revela narrative` means `/revela story`
+- `/revela deck` means `/revela make deck`
+- `/revela brief` means `/revela make brief`
 
 ## Workspace State
 
 Use `DECKS.json` as Revela's current compatibility workspace-state file. Do not write or patch it directly.
 
 Use `revela-decks` for state operations:
+
 - `read` to inspect current workspace state
 - `init` to register discovered source material candidates during workspace initialization
-- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, and risks
-- `upsertDeck` or `upsertSlides` only when explicitly needed by a deck/artifact workflow prompt
-- `reviewNarrative` to run deterministic narrative readiness
+- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, risks, and research gaps
+- `reviewNarrative` to run deterministic story readiness
+- `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` to manage research gap lifecycle
+- `attachResearchFindings` to attach saved findings to research state
+- `applyEvidenceCandidates` only when selected candidates should become 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.
+
+## Init Rules
+
+During init:
+
+- scan local workspace materials before asking broad questions
+- 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
+- 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
+
+## Research Rules
+
+During research:
+
+- start from open research gaps, unsupported central claims, objections, risks, and decision questions
+- run multiple review/search/bind/narrow/re-review loops when useful, stopping when no public evidence can improve the state or after the workflow limit
+- avoid generic internet research when workspace evidence already supports the claim
+- 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
+- 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
 
-Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, or saved research actions as narrative approval.
+## Story Rules
 
-## Narrative Review Rules
+When the user invokes `/revela story`, open the read-only story workspace UI. Do not turn that command into a blocking readiness report.
 
-When reviewing, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
+When the user invokes `/revela review` or explicitly asks for a readiness report, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
 
 Use this report shape:
+
 - `Narrative readiness: <status>`
 - `Narrative hash: <hash>` when available
 - blockers first, with issue type, claim text when available, and suggested next action
 - warnings second, as residual risks
+- research gaps and unattached findings as next work
 - approval state last, clearly distinguishing `ready_for_approval`, `approved`, stale approval, and render override
 
 If evidence is missing, say what is missing and what should happen next. Do not invent quotes, sources, page locations, URLs, caveats, or research findings.
 
-If research findings were saved but not attached or bound, describe them as unattached research state, not proof.
-
 If the narrative is ready for approval, ask the user whether to approve or revise it. Do not approve automatically.
 
+## Make Rules
+
+For `/revela make deck` and compatible deck handoff:
+
+- switch to deck-render mode through the command workflow
+- check narrative readiness and current approval before compiling deck specs
+- 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
+- keep the HTML deck contract valid: one `<section class="slide">` per slide, canonical 1-based `data-slide-index`, and matching `DECKS.json` slide specs
+
+For `/revela make brief`, render the executive brief from canonical narrative state and graph-backed claim/evidence relationships, not from a deck summary.
+
+If story readiness, approval, evidence, or artifact blockers remain, report the blocker and suggest `/revela review`, `/revela research`, or a targeted user answer. Do not bypass with invented state.
+
+## Refine Rules
+
+Use `/revela refine` for post-artifact reading, inspection, and editing.
+
+- Reading should explain source, support strength, caveat, unsupported scope, narrative purpose, related risks/objections, research gaps, and artifact coverage.
+- Pure artifact polish may stay artifact-level: layout, typography, spacing, crop, visual hierarchy, export mechanics, and deck contract fixes.
+- Meaning-changing edits must update canonical narrative first, then run story readiness/approval or explicit override, then remake affected artifacts.
+- Deprecated `/revela edit` and `/revela inspect` route to Refine.
+
+## Design Surface
+
+Use `/revela design` for visual-system work: list/use/new/edit/preview/install/remove designs.
+
+Do not inject design CSS, layout catalogs, component indexes, chart rules, or deck HTML skeletons during init, research, or story. Fetch design context only for make-deck or explicit design-authoring workflows.
+
 ## Boundaries
 
 - Do not write or overwrite `decks/*.html` in narrative mode.
-- Do not call `revela-decks review` in narrative mode; that is the deck/artifact gate.
-- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks.
-- Do not fetch design CSS, layouts, components, chart rules, or HTML skeletons in narrative mode.
+- Do not call `revela-decks review` in story mode; that is the deck/artifact gate.
+- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks or the active workflow requires it with clear support.
 - Do not store secrets, credentials, tokens, or sensitive personal information.
 - Do not infer long-term user preferences from one-off tasks.
-
-When the user wants deck/artifact readiness, direct them to `/revela deck --review`. When they want to render a deck, wait for the explicit deck workflow.
+- If source support is missing, keep the gap visible instead of making the claim sound proven.

package/skill/SKILL.md

@@ -374,7 +374,7 @@ After the user confirms the slide plan, update `DECKS.json` through `revela-deck
 3. Call `revela-designs` tool with `action: "read"` and `component` set to ALL component
    names you plan to use (comma-separated, e.g. `component: "card,stat-card,evidence-list"`).
 4. Use `revela-decks` action `upsertDeck` to mark `requiredInputs.designLayoutsFetched` complete.
-5. Run `/revela review` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
+5. Run `/revela make deck --review` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
 6. Use `revela-decks` action `read` and confirm `writeReadiness.status` is `ready` with no blockers.
 7. Generate HTML that **exactly matches** the fetched examples — copy the HTML structure verbatim.