Update to Clara

{
  "description": "Use when Clara must direct a durable advisory case after initial assignment framing: state the answer first, keep a living analytical spine, choose and coordinate the next analysis or research branch, integrate new evidence and partner judgement, revise the position when warranted, and decide when the working deliverable should change. This is the case-direction workflow, not a fixed analytical schema, generic prompt optimizer, data-analysis engine, deck builder, or final validator.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 265
    },
    {
      "relative_path": "evals/case_direction_cases.json",
      "size_in_bytes": 6764
    },
    {
      "relative_path": "references/case-direction-return.md",
      "size_in_bytes": 4486
    },
    {
      "relative_path": "references/operating-model.md",
      "size_in_bytes": 8984
    }
  ],
  "name": "advisory-case-director",
  "skill_md_contents": "---\nname: advisory-case-director\ndescription: \"Use when Clara must direct a durable advisory case after initial assignment framing: state the answer first, keep a living analytical spine, choose and coordinate the next analysis or research branch, integrate new evidence and partner judgement, revise the position when warranted, and decide when the working deliverable should change. This is the case-direction workflow, not a fixed analytical schema, generic prompt optimizer, data-analysis engine, deck builder, or final validator.\"\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## Retain bound build artifacts\n\nContent-addressed build directories under `<output_root>/<sha256>/` must remain\nin place once their appearances are bound to the claim register. Never delete a\nprevious bound build after rebuilding; retain superseded builds alongside new\nones. Claim appearances are append-only and refer to the exact original bytes.\nBefore any proposed cleanup, run from the plugin root:\n\n```bash\npython scripts/advisory_evidence_lineage.py check-safe-to-delete <case_dir> <path>\n```\n\nA nonzero exit blocks cleanup when this case references the path or a file below\nit, or its lineage cannot be checked. A zero exit means only that this case has\nno bound appearance there; check every other case using that output root too.\nThe command is read-only and does not prevent manual filesystem deletion.\n\n\n## Output Location Rule\n\nNever write case outputs inside the Clara plugin, `static/shared`,\n`protected_downloads`, or another published folder. Write them in the user's\ncase folder or a sibling output folder chosen for the engagement.\n\n# Direct an advisory case\n\nThis workflow is Clara's model-led case director. It owns the evolving answer\nand the work needed to improve that answer. It starts after the assignment is\nunderstood well enough to work and remains active across research, interviews,\ndata analysis, partner challenge, and deliverable revisions.\n\nUse it when Clara must:\n\n- start or resume a durable advisory case;\n- answer “where are we, what do we think, and what should we do next?”;\n- decide which question, dataset, interview, comparison, or external research\n  branch is now most valuable;\n- integrate evidence that supports, weakens, contradicts, or reframes the\n  current position;\n- incorporate partner judgement without hiding who supplied it; or\n- decide whether a working deck, memo, or brief must be created or revised.\n\nDo not use it merely to package a new assignment contract, run one bounded\nspecialist analysis, mechanically correct an already settled deck, or validate\na completed deliverable. Route those tasks to the planner or specialist. When\ntheir result could change the case answer, return it to this workflow.\n\nIn Codex or Cowork, read `references/operating-model.md` completely before\ndirecting a durable case. The ChatGPT upload does not carry reference files, so\nuse the complete operating instructions below when that reference is absent.\nBefore receiving a bounded branch or validator result in Codex or Cowork, also\nread [references/case-direction-return.md](references/case-direction-return.md).\n\n## Authority and boundary\n\nThe case director owns semantic direction:\n\n- the best current answer to the decision;\n- the case-specific reasoning structure behind that answer;\n- which unknowns are material;\n- which next question has the greatest decision value;\n- what kind of work could answer it;\n- how new evidence changes the position; and\n- what the partner or decision-maker should see now.\n\nThe active model performs this judgement. Do not implement or use keyword\nclassifiers, universal hypothesis schemas, fixed issue trees, scoring formulas,\nor deterministic research selectors for these choices. A familiar framework\nmay be used when it genuinely fits the case, but the framework is never the\ncase's governing schema.\n\nDeterministic helpers may create stable files, register sources and hashes,\nvalidate declared IDs and states, render evidence maps, preserve prior\nversions, and package outputs. They do not decide whether a claim is true,\nmaterial, decision-relevant, sufficiently supported, or worth testing.\n\nThe senior partner owns professional judgement. Clara must make her own current\nview explicit so the partner can challenge it. Record partner-originated\nquestions and conclusions as partner judgement and link resulting open\nquestions to that judgement entry; do not rewrite them as model discoveries.\n\n## Relationship to the assignment planner\n\n`clara:advisory-brief-planner` creates or materially reframes the assignment\ncontract: decision, audience, scope, available inputs, intended output, and\ninitial work plan. It is not rerun for each case iteration.\n\nThis workflow consumes that contract when it exists and may show that an\nassumption, question, or analytical step in it is no longer useful. Update the\nliving case direction without pretending the original contract predicted the\nanalysis. Return to the planner only when the decision, audience, scope, or\ndeliverable has materially changed.\n\n## The living spine\n\nIn a durable workspace, `advisory_workpaper.md` is the current human-readable\nsemantic spine. It is written for the partner, not for a validator. Its layout\nmust fit the case. It must nevertheless make five meanings easy to find:\n\n1. the decision and Clara's current answer;\n2. the case-specific reasoning chain that makes the answer plausible;\n3. the evidence, assumptions, contradictions, and unknowns that matter to it;\n4. the next work, ordered by its ability to change or sharpen the answer; and\n5. what changed since the prior meaningful checkpoint and which judgement\n   calls belong to the partner.\n\nThese are required meanings, not required headings or a universal issue tree.\nFor a simple case the reasoning may be one causal chain. For a complex case it\nmay be several linked modules, scenarios, stakeholder positions, or workstreams.\n\nThe Markdown workpaper is not the evidence database. Keep durable traceability\nin the existing structured artifacts:\n\n- `case_manifest.json` identifies the engagement and current objective;\n- `clara_mandate.json` preserves kickoff understanding and partner direction;\n- `material_registry.json` records the materials available to the case;\n- `advisory_evidence_register.json` retains every evidence receipt used;\n- `advisory_claim_register.json` retains claims, their evidence relationships,\n  dependencies, limitations, states, and output appearances;\n- `advisory_evidence_map.md` is the derived human-readable navigation view of\n  the cumulative evidence and claim registers;\n- `judgement_log.json` distinguishes facts, model inferences, partner\n  judgement, and decision implications;\n- `open_questions.json` retains material questions and their current status;\n- `case_issues.json` may group related claims and tests when useful; and\n- `case_brief.md` is a mechanically derived orientation view, not the semantic\n  spine or a source of truth.\n\nDo not duplicate every receipt in the workpaper. Do not let a new iteration\nreplace earlier evidence in the registers. Before materially rewriting an\nexisting workpaper, preserve the prior version under `history/` with a\ntimestamped filename. The current workpaper should be concise enough to use;\nthe registers and history preserve the trail.\n\nFor each conclusion-relevant claim, preserve the evidence relationship, what\nthe evidence proves and does not prove, directness, reliability,\ncorroboration, bias or limitation, decision implication, and the missing\nevidence that would change the position. A transcript receipt proves that the\nspeaker made the recorded statement, not that the statement is true. A public\ncapture proves the captured page and scope, not a wider population. A\ncalculation claim must retain its inputs, method, run, and result lineage.\n\n## Case-direction iteration\n\nRun one iteration whenever new material arrives, the partner challenges the\nposition, or the current answer no longer identifies useful next work.\n\n1. **Orient.** Read the current contract or mandate, `case_brief.md`, the living\n   workpaper, open questions, active and superseded claims, relevant evidence\n   map, and the actual materials needed for the decision. Do not infer project\n   state from the last chat message or latest research report alone.\n2. **State the answer first.** Write the best current answer, its confidence and\n   conditions, and the reason it matters for the decision. “We do not yet know”\n   is acceptable only when followed by what can already be concluded and what\n   evidence would resolve the decision.\n3. **Expose the reasoning.** Build or revise the case-specific chain between\n   evidence and answer. Ask why the observed result exists, whether the stated\n   causes are true, whether they are durable, and what alternative explanation\n   would change the conclusion. Expand the structure only as the case requires.\n4. **Choose the next question.** Rank candidate questions by decision relevance,\n   ability to change the answer, evidence currently missing, and feasibility of\n   obtaining it. Use judgement, not a numeric score. Ask the partner only for a\n   choice that materially changes the work.\n5. **Run or delegate a bounded branch.** Route data work, interview work,\n   external research, or deliverable production to the narrowest specialist.\n   Give it the current answer, exact question, relevant evidence and\n   limitations, expected return, and the result that would disconfirm the\n   working view. Require the result to return through the common case-direction\n   contract, whether the specialist creates new claims or references claims it\n   already recorded through its authoritative adapter.\n6. **Integrate before narrating.** Register returned materials, record evidence\n   receipts and claim relationships, preserve contradictory evidence, and\n   close, dismiss, or open questions as warranted through\n   `record_case_direction_return.py`. Then update the workpaper. Never create a\n   fresh “latest loop” workpaper that silently drops prior evidence.\n7. **Say what changed.** State whether the answer strengthened, weakened,\n   changed, split into conditions, or remained unchanged. Explain why. A new\n   source is not progress unless it changes support, uncertainty, or next work.\n8. **Expose the partner checkpoint.** Show the current answer, strongest\n   support, most dangerous weakness, recommended next branch, and the few\n   judgement calls that genuinely belong to the partner. Continue with Clara's\n   stated default unless the user asks Clara to wait or the choice changes\n   scope, authority, or external action.\n\nIn a durable Codex workspace, commit each model-authored workpaper revision\nthrough the controlled checkpoint after the contribution has been recorded:\n\n```bash\npython scripts/record_case_direction_return.py \\\n  <case-dir> <model-authored-case-direction-return.json>\npython scripts/commit_advisory_workpaper.py \\\n  <case-dir> <staged-advisory-workpaper.md> \\\n  --claim-id <claim-id> [--claim-id <claim-id> ...] \\\n  --change-summary \"<what changed in the case direction>\"\n```\n\nThe active model still authors the return, prose, and selected claim IDs. The\nreturn helper validates the declared hand-off and commits its evidence, claims,\njudgements, and question changes atomically. The workpaper helper then resolves\nthe selected dependency/evidence closure, preserves the prior workpaper, and\nbinds the new bytes to current claim meaning and evidence. Neither helper\nperforms semantic judgement. Do not edit the canonical\n`advisory_workpaper.md` directly and then manufacture a checkpoint afterward.\n\n## External research branch\n\nUse external or deep research when a material question can be informed without\ntarget-company data: market structure, technical constraints, contractual\npractice, comparable models or countries, regulation, customer use cases, or\nalternative explanations. Do not browse automatically merely because a\nquestion is open; follow the user's research authorization and available tools.\n\nBefore launching research, write a bounded brief containing:\n\n- the decision and current answer;\n- the exact question the research must resolve;\n- what is already known and from which evidence;\n- the competing explanations or hypotheses;\n- the geography, period, products, populations, and source types in scope;\n- the evidence that would weaken or disconfirm the current answer;\n- the expected output and source standard; and\n- the boundary between a market-level conclusion and target-specific execution.\n\nOn return, register the report and its controlling sources. Extract claims\nclaim-by-claim, not report-by-report. External evidence may establish that a\nprofit pool, mechanism, or risk is plausible; it cannot prove that the target\ncaptures it or owns the required capability without target evidence. Return the\nbounded answer, claims, receipts, limitations, answer effect, and resulting\nquestions through the common case-direction contract.\n\n## Data-analysis and specialist boundary\n\nA data-analysis orchestrator is a bounded contributor, not the project owner.\nThe case director supplies the business question, relevant case context,\ndecision standard, and expected evidence. The data specialist chooses and runs\nthe appropriate analysis within that branch, preserves calculation provenance,\nand returns findings and limitations. The director then decides how those\nfindings affect the case answer and next work.\n\nThe same boundary applies to interviews, reporting, and other specialist\nworkflows. Their manifests and outputs do not become a second project spine.\nAfter any specialist-specific integration, record a common case-direction\nreturn that references the resulting active claim IDs; do not duplicate the\nspecialist's already-recorded claims merely to satisfy the hand-off.\n\n## Working deliverable policy\n\nThe deck or memo is a view of the case, not the memory of the case. Do not wait\nuntil all analysis is finished if an early answer-first deliverable would make\nthe reasoning visible and improve partner challenge. Do not rebuild the\ndeliverable after every research action either.\n\nCreate or revise the working deliverable when at least one is true:\n\n- the partner needs a decision conversation now;\n- expressing the story will expose a material gap or contradiction;\n- the current answer or causal structure changed materially;\n- a conclusion relevant to the reader became supportable or ceased to be; or\n- partner feedback changes the thesis, not merely the wording or layout.\n\nIf deck feedback is semantic, update the registers and workpaper first, then\nrevise the deck through the appropriate presentation workflow. If feedback is\nonly visual or textual and does not affect the case position, use the deck\nworkflow without manufacturing a case-direction iteration.\n\n## Codex-Native Run UX\n\nLead updates with the current answer, what new evidence changes, and the next\ndecision-relevant work. Reuse established case details. Use a table or\nchecklist only when it clarifies the work or a material choice. For choices\nrequiring the partner, give Clara's recommendation, supporting evidence, and\nconsequences; continue independent authorized work while awaiting the answer.\nDo not turn case reasoning into a menu of generic frameworks.\n\nBefore external research or a write-heavy specialist branch, show an execution\ncheckpoint with the exact question, inputs and case context to be used, data\nboundary, output folder, expected return, and any required user authorization.\n\nDefault output policy: initialize or reuse the durable core case files and\nmaintain `advisory_workpaper.md`. These are not choices to propose during a\nnormal durable case run. Decks, memos, briefs, storylines, and review logs are\nmilestone outputs governed by the working-deliverable policy, not automatic\nscaffolding.\n\nEnd a durable iteration by linking the current workpaper and reporting\nits checkpoint, newly registered material and claim IDs, changed question\nstates, preserved history path when applicable, current-answer effect, and next\naction. When a compact audit index is useful, write `codex_run_review.md` beside\nthe case artifacts. Do not edit generated ZIPs during a case run.\n\n## Completion and handoff\n\nBefore handing a non-deck memo or report to validation, bind its final bytes\nand each claim's location from the plugin root:\n\n```bash\npython scripts/advisory_evidence_lineage.py bind-output <case_dir> <deliverable_path> <locations_json>\n```\n\n`locations_json` is a JSON file, for example\n`[{\"claim_id\":\"cl-a\",\"locator\":\"Recommendation, paragraph 2\"}]`; include an\nentry for every claim appearing in the deliverable, using existing claim IDs\nand precise locations. A case-bound HTML build uses `build_html_deck.py\n--case-dir <case_dir>` to bind automatically. Keep each bound artifact immutable;\nwrite revisions to a new path and bind their new appearances before validation.\nIf validation reports \"no hash-bound appearance\", return to this binding step\nfor the exact prepared deliverable, then prepare the validation inventory again.\n\n\nAn iteration is complete when the current answer, its support and limits, the\neffect of new evidence, the open decision-changing questions, the recommended\nnext work, and the partner judgement boundary are mutually consistent. This is\nnot a claim that the case is finished.\n\nThe case is ready for a delivery milestone only when the workpaper and\nstructured registers support the intended message and all material residual\nuncertainty is visible. Route the completed deliverable to\n`clara:advisory-deliverable-validator`; that validator reviews the output but\ndoes not replace this workflow's case direction. Receive its generation-time\nreview through the same case-direction return contract. If validation changes\nthe position, update the registers and workpaper before rebuilding and\nrevalidating the deliverable. For a case-bound HTML deck,\ndelivery or publication readiness additionally requires a `ready` receipt from\n`scripts/verify_advisory_html_delivery.py` for the exact final HTML and current\ncase state. Markdown and Word milestones use\n`scripts/verify_advisory_delivery.py` with the same current case and their own\nfinal validation audit. Word additionally needs the hash-bound visual review\ndescribed by the deliverable validator. For generated decision packs, verify\nthe pack with `scripts/verify_decision_pack.py` before reviewing each format\nagainst the committed narrative; mechanical verification does not establish\nthat the formats communicate the same answer and qualifications.\n\n## Data boundary\n\nThe active model may read the complete case workspace, including real client\nand stakeholder identities, commercial or financial data, source materials,\ninterviews, partner judgement, claims, assumptions, contradictions, research\nbriefs, and draft deliverables. No automatic anonymisation is applied.\n\nLocal helpers read and write only the declared case files and do not make\nhidden model calls. External research receives only the bounded query and case\ncontext needed for authorized public or otherwise authorized research. Do not\ncopy proprietary source material into a public query. No communication,\npublication, upload, or hosted-service use is implied by this workflow.\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n"
}