Update to Clara

{
  "description": "Correct, revise, or rebuild an existing PPTX or Clara HTML deck from spoken feedback, a call transcript, screen recording, review notes, or partner comments. Use when the user says record feedback on this deck or when the requested outcome is a changed deck rather than only a transcript: open Clara Voice Capture when needed, interpret every requested change, preserve untouched content, require a reviewable understanding and approval checkpoint for PPTX work, apply changes to a copy, render, verify, and inspect the final audience-facing deck. Do not use for transcription alone or for creating a new deck without revision feedback.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 270
    }
  ],
  "name": "deck-correction",
  "skill_md_contents": "---\nname: deck-correction\ndescription: \"Correct, revise, or rebuild an existing PPTX or Clara HTML deck from spoken feedback, a call transcript, screen recording, review notes, or partner comments. Use when the user says record feedback on this deck or when the requested outcome is a changed deck rather than only a transcript: open Clara Voice Capture when needed, interpret every requested change, preserve untouched content, require a reviewable understanding and approval checkpoint for PPTX work, apply changes to a copy, render, verify, and inspect the final audience-facing deck. Do not use for transcription alone or for creating a new deck without revision feedback.\"\n---\n\n<!-- CLARA_OPENAI_ONBOARDING_BEGIN -->\nOnboarding is optional. Continue ordinary professional work immediately,\nincluding direct specialist invocation, without checking or completing a local\nonboarding profile. Missing, unfinished, inaccessible or corrupt onboarding state,\nor unavailable voice/window controls, must never block ordinary work. Do not\nautomatically start, resume or repeatedly offer onboarding.\nOnly for a user-requested tutorial or a native teaching handoff, read\n`../clara/references/local-onboarding.md`. A verified paired lesson worker\nexecutes only its bound lesson and token; never bypass tutorial validation.\nTutorial profiles, progress, examples and feedback remain local; never send a\nchange request, stamp a tutorial receipt or call hosted interviews for a tutorial.\nCurrent user requests take precedence over saved preferences.\n<!-- CLARA_OPENAI_ONBOARDING_END -->\n\n# Deck Correction\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n\n## Output Location Rule\n\nNever write run outputs inside this Git workspace, `static/shared`,\n`protected_downloads`, or another static-site folder. Keep the corrected deck,\nrendered slides, revision artifacts, and `codex_run_review.md` in the user's case\nor adjacent project/output folder.\n\nUse this skill when feedback must become a verified deck change. The analytical\nmeaning of the feedback is model-led work; deterministic helpers may prepare\nevidence, validate contracts, apply explicit patches, and verify mechanics, but\nmust never decide what the speaker meant from keywords, slide numbers, or visual\nmatching alone.\n\nComplete interpretation, user review, application, rendering, verification,\nand final output review. Use a persistent goal only when explicitly requested\nby the user; otherwise use a proportionate plan without pausing intake to\ncreate a goal.\n\n## Route by Target Format\n\n- **PPTX:** use the Clara deck-revision harness below and the installed\n  presentation-editing capability. Keep the original untouched and edit a copy.\n- **Clara HTML deck:** use the `html-deck` preservation-aware revision workflow.\n  Build a revision map from the approved change ledger, protect untouched\n  slides/components/runtime, apply only mapped changes, and prove before/after\n  fidelity through browser and render QA.\n- **No existing deck:** this is creation, not correction. Route to the normal\n  presentation or `html-deck` creation workflow after clarifying the target\n  format.\n\nIf the feedback comes from audio or video, use `transcribe` first when no clean\nreviewed transcript exists. A hosted external interview is not a deck-correction\ninput until its bundle has been retrieved and the user explicitly asks to use\nthat evidence.\n\nWhen the deck belongs to a case with advisory lineage, preserve that history as\nwell as the original file. An unchanged claim keeps its upstream claim ID and\ngains an appearance for the corrected deck. Changed wording creates a new claim\nwhose `supersedes_claim_id` points to the old claim; removed wording leaves the\nold claim withdrawn or superseded rather than deleting it. New or changed\nevidence gets a new receipt. Rerun Claim Basis Map, HTML Deck, or Reporting\nEngine checks as applicable. These lineage updates do not replace this skill's\napproval, copy, render, visual QA, or before/after verification gates.\n\nRun dependency checks from the plugin directory:\n\n```bash\npython scripts/check_dependencies.py\n```\n\nInstall declared requirements only when the environment permits.\n\n## One-Command Live Feedback Capture\n\nWhen the user says **“Clara, record feedback on this deck”** or equivalent,\ndo not ask them to find a server URL, open a desktop shortcut, locate the\ndownloaded bundle, or run an import command. Resolve the current Clara case and\ntarget deck from inspected context. Ask one short question only when either is\nmaterially ambiguous, then run:\n\n```bash\npython scripts/start_deck_feedback.py <case-dir> \\\n  --deck <existing-deck.pptx-or-html> \\\n  --browser chrome\n```\n\nRun this as a continuing process and keep the user informed while they record.\nThe helper opens the authorized context-bearing Voice Capture page, ignores\nolder downloads, waits for the newly completed bundle, imports it into the\ncase, and writes `deck_feedback_capture.json` in the imported voice session.\nFor PPTX it also refreshes the deck-revision intake against the exact target\ndeck. For HTML, read the handoff and follow the preservation-aware HTML path\nbelow. After import, complete speaker attribution when needed and continue the\nnormal interpretation and revision workflow; do not send the user back to the\nDownloads folder.\n\nFor captured Clara HTML decks, inspect the imported `active_slide_timeline`\nand transcript `active_slide_id` fields first. Resolve the captured ID in the\nactual target HTML and corroborate the capture session, deck title, visible\ncontent and time interval. A title alone does not establish deck identity, and\ncapture handles do not carry a source-file hash. Once that identity is verified,\nuse the captured slide ID ahead of visual similarity candidates. If identity\nor timing conflicts, retain the conflict for model inspection rather than\nchoosing an edit target automatically. These IDs are not supplied for ordinary\nPPTX screen capture; use its frames and deck snapshot instead.\n\nIf the capture process is interrupted, preserve the existing local case and\nreport whether the browser launch, new-bundle detection, or import failed. Fall\nback to `import_latest_hosted_voice_bundle.py` only when a completed bundle is\nalready present but the continuing process was lost.\n\n## Required Authorities\n\nBefore editing, establish:\n\n- **case/evidence authority:** the relevant case context, transcript, notes,\n  call/video provenance, and supporting materials;\n- **visual authority:** the current deck plus its inherited or explicit style\n  profile;\n- **method authority:** evidence-aware, room-safe advisory wording and the\n  distinction between source claims, user requests, and Clara interpretation.\n\nDo not fabricate missing replacement wording, quotes, evidence, chart data, or\nstyle rules. If a requested change lacks source material or a decision, keep it\nvisible as blocked or `needs_human_decision`.\n\n## PPTX Intake and Interpretation\n\nPrepare the intake after the transcript is attributed and the existing deck is\nknown:\n\n```bash\npython scripts/prepare_voice_deck_revision.py <case-dir> \\\n  --deck <current-deck.pptx>\n```\n\nAdd `--deck-style` or `--company-profile` when style authority is not already\nresolved. The intake snapshots the deck/style evidence and may attach\nconservative rendered-slide match candidates. Those matches are navigation\nevidence only.\n\nNear-identical slides can tie even at a similarity score of 1.0. Inspect all\ncandidate slides for low-confidence matches, and inspect every relevant frame\nwhen a feedback unit spans multiple slides; its summary reports only the best\nframe match. Letterboxing, partial animation builds and poor screenshots can\nobscure the distinguishing text. No similarity score authorizes an edit or\nsubstitutes for interpreting the feedback against the visible source.\n\nBuild the workbench and focused interpretation packets:\n\nFor resumable preparation, run this after intake and again after authoring or\nrevising the change list:\n\n```bash\npython scripts/run_deck_revision.py <case-dir> --voice-session voice_sessions/<timestamp>\n```\n\nRead `deck_revision_runner.json` for the current stage, material gaps and next\naction. The runner reuses byte-identical generated views, rebuilds changed\ndependencies, and requires renewed model interpretation when evidence changes.\nIt never writes approval or final-review confirmations. Once current approval\nexists, add `--apply-approved` to apply supported changes and resume from their\nexact output hashes. Repeating that command reuses unchanged application and\nchecks any recorded final review against current inputs and confirmations.\n`final_review_record_current` verifies the recorded review, not that the runner\nperformed visual or semantic inspection. Perform that review with the commands\nbelow. The individual preparation commands remain available for focused inspection:\n\n```bash\npython scripts/build_deck_revision_workbench.py <case-dir>\npython scripts/build_deck_revision_interpretation_packets.py <case-dir>\n```\n\nCodex inspects the packets and writes\n`deck_revision_changes.json`. Every change must carry:\n\n- the requested change and its transcript/review evidence;\n- Clara's interpretation and uncertainty;\n- scope and affected slides;\n- execution strategy;\n- concrete success criteria;\n- packet/dependency metadata when relevant.\n\nUse `packet_scope: \"deck\"` for global font, order, insertion, deletion, or other\ndeck-level changes. High/medium visual matches may ground location; low/no\nmatches are navigation hints only.\n\nFinalize the consultant-readable understanding:\n\n```bash\npython scripts/finalize_deck_revision_plan.py <case-dir> \\\n  voice_sessions/<timestamp>/deck_revision_changes.json\n```\n\nThe finalizer validates evidence and slide references, ignores model-authored\napproval flags, and writes the normalized plan plus\n`deck_revision_understanding.md`. Do not edit the PPTX yet.\n\n## Execution Planning and Material Gaps\n\nBuild explicit execution routes and packets:\n\n```bash\npython scripts/build_deck_revision_execution_plan.py <case-dir>\npython scripts/build_deck_revision_execution_packets.py <case-dir>\npython scripts/analyze_deck_revision_materials.py <case-dir>\n```\n\nStrategies are `deterministic_patch`, `model_assisted_edit`, `slide_rebuild`,\n`deck_restructure`, or `needs_human_decision`. Execute one focused packet at a\ntime. If a deck-level packet changes order or slide count, refresh later slide\nreferences before continuing.\n\nSupported automatic patches are intentionally narrow: `set_title_text`,\n`set_shape_text`, `replace_text`, `add_textbox`, `delete_shape`, and\n`move_shape`. Existing-object patches need concrete target identity and expected\npre-edit text. Route unsupported or judgement-heavy changes to the appropriate\nmodel-assisted or human path.\n\nWhen changes request better quotes or interview evidence, build and inspect the\ncandidate matrix before selecting copy:\n\n```bash\npython scripts/build_deck_revision_quote_candidate_matrix.py <case-dir>\n```\n\nThe matrix finds candidates; Clara/Codex still judges relevance, source\ndiversity, sharpness, and room-safe wording.\n\n## PPTX Approval and Application\n\nShow `deck_revision_understanding.md` to the user. Only after that review write\nthe hash-bound approval artifact:\n\n```bash\npython scripts/approve_deck_revision_plan.py <case-dir> \\\n  --reviewer \"<name>\" --understanding-reviewed\n```\n\nIf the normalized plan or understanding changes, approval is stale and must be\nrenewed. Apply supported patches only after approval:\n\n```bash\npython scripts/apply_deck_revision_plan.py <case-dir>\n```\n\nThe applier writes a corrected copy, apply report, verification artifacts, and\nan output-review checklist. A successful script exit is not proof that the deck\nis ready; semantic/manual success criteria and the visible render still require\nreview.\n\nRender and inspect every changed slide and enough surrounding slides to catch\nsequence effects. Check audience-facing titles/copy, numbers, charts, footers,\nclipping, overlap, stale artifacts, internal instructions, process language,\nand semantic drift. Iterate until no material issue remains, then complete the\nexact-output review:\n\nFor an approved structural edit, slide rebuild, or other externally edited PPTX,\nkeep the original deck and save the edited result separately. Register that\nresult without running automatic patches over it:\n\n```bash\npython scripts/apply_deck_revision_plan.py <case-dir> \\\n  --register-external <edited-deck.pptx>\n```\n\nRegistration requires the current approved plan and understanding, checks the\nplan's mechanical criteria, and preserves the submitted PPTX bytes. It creates\nthe same exact-output review packet used below; it does not perform semantic or\nvisual review. Failed or unsupported mechanical checks must be resolved before\nregistration. Explicit manual/semantic criteria remain pending in the registered\nreview packet; they are not converted into mechanical passes. The runner reports pending or stale external review and preserves\nthe external deck even when `--apply-approved` is supplied. After revising an\nexternal deck, verify and register it again rather than reapplying automatic\npatches from the original source.\n\nThe output-review packet binds the corrected deck, original source deck,\nnormalized plan, approval, understanding and verification report by hash.\nCompletion rejects changes to any of these inputs and packets created through\nunapproved diagnostic application. After changes, rerun approved application for\nautomatic patches or register the external result again, and inspect the new\noutput before recording completion.\n\n```bash\npython scripts/complete_deck_revision_output_review.py <case-dir> \\\n  --reviewer \"<name>\" \\\n  --audience-copy-reviewed \\\n  --process-language-reviewed \\\n  --requested-structure-reviewed \\\n  --semantic-evidence-fit-reviewed \\\n  --visual-render-reviewed\n```\n\nWhen the verification report lists pending manual or semantic criteria, inspect\neach against the exact registered output and supply `--criterion-reviews\n<reviews.json>` to completion. The JSON must contain exactly those criterion IDs,\neach with `{\"reviewed\": true, \"note\": \"Concrete observation supporting this review\"}`.\nRecord specific observations, not a blanket pass. Completion stores these notes\nagainst the hash-bound review packet and refuses missing or incomplete reviews.\nNo criterion review substitutes for the rendered inspection or other confirmations.\n\nDo not present the corrected PPTX as final until the completion artifact exists\nfor the exact reviewed output.\n\nIf the deck is part of an advisory-deliverable validation, completion here is\none authoritative format gate, not the final advisory decision. Run the\nadvisory validator's `prepare` command again on the corrected deck, complete a\nsecond model-led claim-chain review, and supply that corrected inventory and\nreview to the original validation package. A correction is not delivery-ready\nmerely because the deck-correction completion record passed.\n\n## HTML Preservation Path\n\nFor an existing HTML deck, read and follow the full `html-deck` revision\nworkflow. The correction evidence becomes an explicit change ledger; it does\nnot authorize global cleanup. Inspect the existing deck, create a revision map,\nprotect untouched slide IDs/components/styles/runtime, apply only mapped edits,\nrun static and multi-viewport browser QA, render the result, and compare it with\nthe baseline. Report both intended changes and any unexplained drift.\n\nThere is no PPTX-style hash approval helper for HTML. Still show the interpreted\nchange ledger before a materially ambiguous or broad revision and resolve\nconsequential ambiguity before applying the affected changes.\n\nWhen the HTML deck belongs to a Clara advisory case, rebuild with `--case-dir`,\nrerun the model-led advisory validator for the corrected bytes, and rerun\n`verify_advisory_html_delivery.py`. The prior delivery receipt is stale by\ndefinition; unchanged claims gain a new exact appearance, while changed claims\nmust already have been recorded as new or superseding claims upstream.\n\n## Codex-Native Run UX\n\nSummarize the source deck, feedback, output copy, and any unresolved material\nchoice when needed for review. Use tables or a checklist only when they clarify\nthe correction. Reuse established format, style, and case decisions.\n\nDefault output policy: preserve the original, produce one corrected deck plus\nits interpretation, approval, verification, and render-review evidence. These\nare not choices to propose when the user asked for the normal deck-correction\nrun. For PPTX, the reviewed understanding and hash-bound approval checkpoint are\nmandatory before application.\n\nBefore long or write-heavy work, show an execution checkpoint naming the source\ndeck, approved plan hash where applicable, output path, packet scope, and\nexpected verification. At delivery, link the original and corrected\ndeck, interpreted changes, approval state, verification, render-review state,\nand residual manual items. Create `codex_run_review.md` when blocked or when a\nrepeatable correction gap should survive the chat. Never edit generated ZIPs\nduring a run.\n"
}