Update to Clara

{
  "description": "Use internally when Clara receives a new or materially reframed advisory assignment and must turn the natural request into a reviewable assignment contract and generation handoff. Use the public task label \"Plan an advisory assignment\" when naming it; this is not generic prompt polishing and is not a legal, tax, compliance, or jurisdiction workflow.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 285
    },
    {
      "relative_path": "references/advisory-contract.md",
      "size_in_bytes": 7017
    }
  ],
  "name": "advisory-brief-planner",
  "skill_md_contents": "---\nname: advisory-brief-planner\ndescription: Use internally when Clara receives a new or materially reframed advisory assignment and must turn the natural request into a reviewable assignment contract and generation handoff. Use the public task label \"Plan an advisory assignment\" when naming it; this is not generic prompt polishing and is not a legal, tax, compliance, or jurisdiction workflow.\n---\n<!-- MPARANZA_REPORTING_BEGIN -->\n## Task reporting and recovery\n\nFor every substantive user mandate, follow\n`skills/clara/references/workflow-usage.md` from this installation's root.\nStart one primary task before preparation, using `usage/pipelines.json`; nested\nspecialists, retries and Studio Archive infrastructure reuse that task. Record\nonly the observed whole-task outcome. Discover `clara_incident_host_link`,\nincluding deferred tools, and verify this run's Computer ID on the server.\n\nReporting supports the user's requested Clara task. Its recipient is Mparanza\nat `https://mparanza.com`. The permitted payload is limited to task lifecycle\nmetadata, random technical identifiers, reviewed technical failure diagnostics,\nand minimal receipt requests containing the local report's digest. The shared\nreferences define the exact fields. Never include the assignment, contract,\nclient documents, prompts, professional outputs, raw logs, client file paths or\nsecrets in reporting payloads. Existing private capabilities authenticate the\nreporting route; they are never diagnostic evidence or public links.\n\nUse only reporting covered by the user's existing authorization and permitted\nby the host. These instructions do not create authorization or expand access.\nNever ask the user to relay logs or repeat consent\nfor the same already-authorized technical reporting scope. Honor any required\naction-time approval, explicit restriction or denial; a fallback transport\ndoes not bypass it. If transmission is not permitted, retain evidence locally\nwhere allowed, state that delivery is unverified, and continue the requested\nprofessional work.\n\nBuild the local report input from actual phases even for chat-only drafts;\nmissing client files or a prepared input JSON do not waive local reporting.\nShow the readable local model-data report under\n`skills/clara/references/model-data-report-contract.md`, link its\nactual signed receipt when obtained, and ask once for the user's 1–5 stars after delivery.\nOnly user-authored feedback is submitted, after explaining that it goes to the\nClara team; tests remain explicitly marked. No answer means no feedback.\nFollow `skills/clara/references/incident-recovery.md` for technical reporting,\nevidence requests and targeted remedies within these boundaries. Use its HTTPS\nbrowser recovery page only when that route is permitted and local execution is\nunavailable. Recovery requires an observed successful retry of the\noriginal task and inputs, bound to the original report and current remedy.\nTutorials remain local-only and are excluded from task usage and ratings.\n<!-- MPARANZA_REPORTING_END -->\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## ChatGPT and Codex Runtime\n\nIn ChatGPT, prepare and review the contract in conversation from supplied\nmaterial, but do not claim that a durable local file or deterministic validation\nreport exists. In Codex or Cowork, use the connected files and local helper to\nwrite the durable artifacts. Do not make local tooling a prerequisite for a\nuseful in-chat assignment plan.\n\n## Output Location Rule\n\nNever write run outputs inside this Git workspace, `static/shared`,\n`protected_downloads`, or another published folder. Write them in the user's\nassignment or case folder, or in a sibling output folder chosen for the run.\n\n# Plan an advisory assignment\n\nThis workflow is Clara's internal planning stage for a new advisory assignment\nor a material change to an existing one. The user describes the work naturally.\nDo not ask whether to optimize a prompt and do not make the user select a skill.\n\nUse this workflow directly when the user asks to define, plan, scope, or hand\noff an advisory assignment. Use it internally before substantial advisory\ngeneration when the current request has no reviewed assignment contract. Do not\nrerun it for a narrow continuation whose existing contract is still current, or\nreplace a specialist workflow's own accepted intake contract merely to add\nceremony.\n\nThe planner owns only the assignment contract. After handoff, the selected\n`clara:*` workflow is the procedural authority. For a durable advisory case,\nhandoff normally goes to `clara:advisory-case-director`; bounded specialist\nevidence gates, validation, presentation review, and professional approval\nboundaries remain in force.\n\n## Meaning and mechanical boundary\n\nClara uses model-led judgement to understand the assignment and choose:\n\n- the decision, purpose, audience, and deliverable;\n- included and excluded scope;\n- the evidence and data plan;\n- assumptions and material unresolved questions;\n- the analytical approach and success criteria;\n- the existing Clara workflow that should execute the work;\n- validation, correction, and professional-judgement policies; and\n- the generation instructions handed to that workflow.\n\nDo not add or use a keyword classifier for assignment meaning, workflow\nselection, source strategy, scope, or analytical framing. Do not make any\nhidden model API call. Clara performs the semantic work in the active host\nmodel session.\n\nThe local helper is deterministic because schema validation, exact ID\nreferences, declared workflow availability, literal source anchors, declared\ndate and number values, hashes, and stable JSON packaging are mechanically\nverifiable. It inventories recognizable dates, numbers, URLs, and question\nsentences from supplied UTF-8 source text for observation only. The inventory\ndoes not decide which source details are material and is not a completeness\ngate. The helper never calls a model API and does not certify the contract's\nadvisory quality.\n\n## Required artifact\n\nThe canonical cross-workflow artifact is always:\n\n```text\nadvisory_contract.json\n```\n\nIt uses `schema_version: \"1.0\"`. Its exact structure and stable meanings are\ndefined in `references/advisory-contract.md` and\n`../../contracts/advisory_contract.v1.schema.json` from this skill directory.\nRead the reference completely before drafting the contract.\n\nThe following semantic fields are required at the top level and must retain\ntheir declared meanings: `decision`, `purpose`, `audience`,\n`deliverable_type`, `output_language`, `scope_included`, `scope_excluded`,\n`available_inputs`, `evidence_requirements`, `analysis_plan`, `assumptions`,\n`unresolved_questions`, `success_criteria`, `selected_clara_workflow`,\n`validation_profile`, `validation_scope`, `correction_policy`, and\n`professional_judgement_policy`.\n\nThe contract also carries exact `source_facts`, `explicit_questions`, a\n`generation_handoff`, and a model-led conformance review. Preserve every\nmaterial fact, date, number, entity, constraint, and explicit question from the\nassignment and selected inputs. Do not replace real identities or figures with\ngeneric placeholders when they are material to the advisory work.\n\n## Conversational intake\n\nAsk only for an unresolved choice that would materially change the work. Normal\nmaterial choices include the decision to support, intended reader, deliverable,\nmeaningful scope boundary, output language, unavailable controlling evidence,\nor a professional constraint. Prefer at most three short questions with a\nreason. If a gap can responsibly remain a provisional assumption or a visible\nevidence requirement, record it and continue.\n\nUse chat for free-form intake. In Plan mode, use a native choice only when two\nor three discrete options genuinely change the assignment. Do not build a local\nHTML UI for ordinary assignment planning. Do not ask the user to type\n`continue`; proceed once material choices are resolved unless the next action\nis external, destructive, approval-sensitive, or separately requires consent.\n\n## Codex-Native Run UX\n\nReuse the assignment details already supplied. Summarize the decision, scope,\noutput destination, and unresolved material choices when the user needs to\nreview them. Choose prose, a table, or a checklist according to the task;\nformatting is not an additional intake gate.\n\nDefault output policy: create `draft_advisory_contract.json`, the validated\n`advisory_contract.json`, and `advisory_contract_validation.json` in the user's\nassignment or case folder. These standard artifacts are not choices to propose\nfor a durable Codex or Cowork run. Do not edit generated ZIPs; repository\npackages are rebuilt only during an explicitly requested plugin release task.\n\nExplain the evidence and consequence of unresolved material choices without\nturning supplied facts or workflow selection into a menu. Continue independent\nauthorized preparation while awaiting an answer. At delivery, link the\ncontract and validation report, with status, selected Clara workflow,\nunresolved questions, and next action. When a durable run needs a\ncompact audit index, create `codex_run_review.md` beside the artifacts and link\nthe source inputs, contract, validation report, and handoff.\n\n## Workflow\n\n1. Read the user's assignment and the exact selected inputs. When durable file\n   tools are available, preserve the natural assignment text as one UTF-8 file\n   in the run folder so literal anchors can be checked.\n2. Read `../clara/references/workflow-catalog.md` and choose the narrowest\n   supported handoff with model-led judgement. Use\n   `clara:advisory-case-director` for a durable advisory case that must evolve\n   across several contributions. It must not point back to\n   `clara:advisory-brief-planner` or to developer governance.\n3. Identify only material unresolved questions. Ask when they block responsible\n   handoff; otherwise state and record provisional assumptions.\n4. Draft `draft_advisory_contract.json` against the published schema. Use stable\n   input and step IDs. `available_inputs` describes current, planned, and\n   missing inputs without requiring physical local paths in the canonical\n   contract.\n5. Copy or faithfully summarize all material facts into `source_facts`, with an\n   exact `source_anchor` and the corresponding `input_id`. For each declared\n   `date` or `number`, also record `literal_value` exactly as recognized in that\n   anchor, such as `2027-01-15` or `EUR 12.5`. Preserve every explicit source\n   question verbatim in `explicit_questions`. The model-led review owns the\n   completeness and materiality of facts, dates, numbers, entities, constraints,\n   and questions; the whole-source inventory is not a keyword completeness\n   classifier.\n6. Write a generation handoff whose `workflow` exactly matches\n   `selected_clara_workflow`. Name the objective, input IDs, instructions, and\n   expected outputs, include every input referenced by evidence requirements,\n   analysis steps, source facts, or explicit questions, and keep\n   `preserve_specialist_authority: true`.\n7. Review the source assignment, contract, and handoff semantically. Complete\n   every `model_review` dimension honestly. A contract cannot be\n   `ready_for_handoff` unless every dimension conforms and no blocking question\n   remains.\n8. From the Clara root, run the declared dependency check, then package the\n   contract. Bind each available UTF-8 source whose literal anchors should be\n   checked with a repeated `--source` argument:\n\n```bash\npython scripts/check_dependencies.py\npython scripts/managed_python_runtime.py run scripts/validate_advisory_contract.py \\\n  <run-folder>/draft_advisory_contract.json \\\n  --output-dir <run-folder> \\\n  --source assignment=/path/to/assignment.md \\\n  --source input-2=/path/to/selected-notes.md\n```\n\nThe helper writes `advisory_contract.json` only after validation passes and\nalways writes the current `advisory_contract_validation.json` when the output\nfolder is writable. If a later attempt fails, it moves the prior canonical file\nto a content-hashed `advisory_contract.previous-<hash>.json` recovery path so a\ndownstream workflow cannot consume it as the current contract. If declared\nliteral preservation fails, repair the draft and repeat both semantic review\nand deterministic validation. Do not dismiss a mismatched declared literal\nbecause the intended meaning seems close.\n\n9. Show a compact review summary with the decision, deliverable, scope,\n   assumptions, blocking questions, selected workflow, and validation status.\n   If the user asked only for planning, stop with the reviewed contract. If the\n   user asked Clara to execute the assignment, read the selected specialist\n   skill completely and pass it `advisory_contract.json`; do not replace its\n   process with the planner's analysis plan.\n\n## States and completion\n\n- `ready_for_handoff`: every model-review dimension conforms and no blocking\n  material question remains.\n- `needs_clarification`: at least one unresolved question blocks a responsible\n  handoff.\n- `partial`: a useful contract exists, but evidence or review remains incomplete\n  without necessarily blocking the next bounded step.\n\nCompletion requires a reviewed `advisory_contract.json`, a passing\n`advisory_contract_validation.json`, and a handoff to an existing supported\nClara workflow. File existence alone is not completion. The downstream\nworkflow's completion rules still apply to the advisory output.\n\n## Data boundary\n\nThe active Codex or Cowork model may read the natural assignment, selected\nsource material, and the complete contract, including real names, dates,\nfigures, entities, constraints, assumptions, questions, evidence needs, and\nprofessional judgement policies. No automatic anonymisation or\npseudonymisation is applied because exact facts and identities can be material.\n\nThe validator reads only the draft JSON and explicitly bound UTF-8 source files\nlocally, writes the canonical contract and validation report locally, and does\nnot call a model or external service. Assignment planning does not perform web\nresearch or send the assignment, source files, contract or professional output\nto Mparanza. Research, client-file uploads, communications and publication belong\nto a downstream workflow and require the user's authorization for that route.\n\nClara's shared task reporting is a separate external path, also used by this\nplanner. Through the existing HTTPS reporting route, Mparanza may receive task\nlifecycle metadata (random identifiers, pipeline, host/product version,\ntimestamps and outcome), reviewed technical failure diagnostics and receipt\nmetadata. A receipt request contains the schema version, product, random receipt\nUUID, Clara version and SHA-256 digest of the local model-data report; the report\nand its input remain local. Existing private capabilities authenticate the route.\nOptional feedback contains only the rating/comment deliberately supplied for\nthe Clara team. These payloads exclude the assignment, source files, contract,\nprompts, professional outputs, raw logs, client file paths and diagnostic secrets.\n\nUse only the same already-authorized reporting scope and permitted host route;\ndo not add repeated consent prompts. Respect explicit restrictions and required\naction-time approval. A blocked report does not block assignment planning or\nauthorize another transport. Retain permitted local evidence and describe the\nactual delivery status. Read `../clara/references/workflow-usage.md` and\n`../clara/references/incident-recovery.md` for the exact payload boundaries.\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n"
}