canon-system-shaping

name	canon-system-shaping
description	Use when you need a governed Canon system-shaping run to shape a new system with mandatory critique and persisted evidence.

Canon System Shaping

Support State

• available-now
• default visibility: discoverable-standard

Purpose

Start a real Canon system-shaping run from your AI assistant without making the user memorize the raw CLI.

When To Trigger

• The user is discussing a new-system workflow and wants a governed shaping run.
• The user has a brief or note with explicit intent and constraints for a bounded system-shaping analysis.

When It Must Not Trigger

• The user already has a run id and wants inspection, approval, or continuation actions.
• The user only needs early bounded framing; use $canon-requirements.

Required Inputs

• RISK
• ZONE
• SYSTEM_CONTEXT
• at least one input file, input folder, or inline note

Optional:

• OWNER when the user wants to override Git-derived ownership explicitly

Preflight Profile

• Verify canon is on PATH. If missing, point to the install guide.
• Verify .canon/ exists. If missing, point to $canon-init.
• Verify risk, zone, SYSTEM_CONTEXT, and at least one authored input are present before invoking Canon.
• Treat authored inputs under canon-input/ as read-only source material. Do not rewrite, normalize, append to, or otherwise modify the user's input files during preflight, clarification, generation, critique, or summary.
• Ask for SYSTEM_CONTEXT explicitly with guided fixed choices new or existing; do not infer it from the mode name alone.
• For auto-binding only, treat canon-input/system-shaping.md or canon-input/system-shaping/ as the canonical authored-input locations for this mode.
• For an explicit inline note, pass it through --input-text instead of materializing a repo file automatically.
• Never infer --input from the active editor file, open tabs, recent .canon/ artifacts, or any other path under .canon/.
• If neither canonical location exists and the user did not provide an explicit input or inline note, ask explicitly for the input path or inline note.
• OWNER is optional. If omitted, Canon should try repository-local or global Git identity before asking for explicit owner input.
• If the user is starting from a short note instead of a structured brief, guide them to include explicit Intent: and Constraint: markers before invoking Canon.
• If the selected file, folder, or inline note is empty, whitespace-only, or structurally insufficient, surface that as invalid authored input and retry only that slot.
• If risk and/or zone are missing after the authored input surface is known, use canon inspect risk-zone --mode system-shaping --input <INPUT_PATH> to infer a provisional pair, explain the Canon rationale and confidence, and ask the user to confirm or override before invoking Canon.
• If the inferred classification returns low confidence, present it as provisional and invite override rather than treating it as final.
• Classification confirmation is intake confirmation only, not Canon approval.
• If risk is invalid, ask with guided fixed choices: low-impact, bounded-impact, or systemic-impact.
• If zone is invalid, ask with guided fixed choices: green, yellow, or red.
• Do not show preflight checks to the user. Report only the specific missing input.

Author System-Shaping Body Before Invoking Canon

Canon does not invent the system-shaping body for you. Canon governs, validates, and persists the packet. You (the assistant) MUST author the real system-shaping body from the bounded source material BEFORE calling canon run --mode system-shaping.

Do this every time, even when the user starts from a short brief rather than a finished packet:

1. Read the source inputs the user pointed at. Identify the target capability, the named stakeholders, the candidate bounded contexts, the domain responsibilities, the vocabulary that needs alignment, and the invariants later modes must preserve. Do not guess.
2. Compose a single system-shaping brief at canon-input/system-shaping.md or a folder-backed packet under canon-input/system-shaping/. The authored body MUST include the following canonical H2 sections with concrete content tied to the source you just read:

• system-shape.md
  • ## System Shape
  • ## Boundary Decisions
  • ## Domain Responsibilities
• domain-model.md
  • ## Candidate Bounded Contexts
  • ## Core And Supporting Domain Hypotheses
  • ## Ubiquitous Language
  • ## Domain Invariants
  • ## Boundary Risks And Open Questions
• architecture-outline.md
  • ## Structural Options
  • ## Selected Boundaries
  • ## Rationale
  • ## Why Not The Others
• capability-map.md
  • ## Capabilities
  • ## Dependencies
  • ## Gaps
• delivery-options.md
  • ## Delivery Phases
  • ## Sequencing Rationale
  • ## Risk per Phase
• risk-hotspots.md
  • ## Hotspots
  • ## Mitigation Status
  • ## Unresolved Risks

3. Intent: and Constraint: remain required inline markers because the runtime uses them to decide whether system-shaping has enough bounded evidence to proceed.
4. Inline labels such as Contexts: or Vocabulary: do not satisfy this slice. Near-miss headings such as ## Boundary Decision do not satisfy it either. Use the canonical H2 headings above.
5. Canon preserves those authored sections verbatim in the emitted packet. If a required section is missing or empty, Canon emits ## Missing Authored Body naming the missing canonical heading instead of fabricating filler.
6. If you cannot author a credible system-shaping body from the available source, stop and redirect to $canon-requirements or ask targeted clarification questions before invoking Canon rather than submitting an empty brief.

Packet Shape And Persona

Author the packet as a system shaper and bounded system designer producing a domain map plus structural-options brief for downstream architects and implementers.

• Favor candidate bounded contexts, boundary decisions, structural options, tradeoff rationale, and delivery consequences over abstract vision statements.
• Treat domain-model.md as the domain-map spine of the packet and architecture-outline.md as the structural-options comparison surface.
• Make rejection logic explicit when more than one structural option remains viable; reviewers should be able to see why the losing options lost.
• Keep recommendations bounded to the authored intent and constraint markers; do not imply organizational approval or operational certainty the source does not support.
• Persona guidance is presentation only. Missing authored sections remain explicit gaps and must not be backfilled with systems-language prose.

Canon Command Contract

• Canon command: canon run --mode system-shaping --system-context <SYSTEM_CONTEXT> --risk <RISK> --zone <ZONE> [--owner <OWNER>] (--input <INPUT_PATH> | --input-text <INPUT_TEXT>)
• Return the real Canon run id, state, and any approval target Canon emits.

Refinement Lifecycle

• System shaping is one of Canon's five targeted planning modes with first-class same-run refinement.
• During draft clarification, Canon may materialize .canon/runs/<RUN_ID>/artifacts/system-shaping/working-brief.md while keeping canon-input/ read-only.
• Candidate detection is advisory. Continuation requires explicit intent.
• Fresh intake stays a new run unless the user explicitly says continue, refine, or same run, supplies a RUN_ID, or chooses Canon's explicit continuation path.
• Pre-start corrections across the targeted planning modes stay on the same run id. After a run has started, mode redirection creates a successor run with carried-forward lineage instead of mutating the original run in place.
• Use $canon-status for the compact summary and canon inspect refinement --run <RUN_ID> when the user needs the working-brief path, clarification records, readiness delta, or lineage.

AI Companion Operating Model

After preflight succeeds and the real Canon run exists, the assistant is responsible for turning the system-shaping packet from templated stubs into a grounded, reviewable artifact set.

Run Boundary

• Read the full authored input surface before generation. If the input is a directory such as canon-input/system-shaping/, treat the directory as one authored packet and read it recursively before generation.
• Start the real Canon run before artifact writing so .canon/artifacts/<RUN_ID>/system-shaping/ exists and the packet stays attached to a real run id.
• Treat authored inputs under canon-input/ as read-only source material. Do not rewrite, normalize, append to, or otherwise modify the user's input files during preflight, clarification, generation, critique, or summary.
• Write generated content only into Canon-managed files under .canon/artifacts/<RUN_ID>/system-shaping/.
• Keep unanswered ambiguity explicit in the generated packet or provenance sidecar instead of quietly guessing.

Generation Loop

1. Read the authored input surface and extract the stated intent, declared constraints, target system boundary, candidate components or capabilities, and the explicit open questions already present in the source.
2. Start the Canon run and inspect the generated system-shaping stubs under .canon/artifacts/<RUN_ID>/system-shaping/.
3. If the source is sufficient, generate the packet directly. If it is structurally sufficient but materially ambiguous, run the clarification loop before final generation.
4. Draft each artifact so every nontrivial claim is grounded in the authored input, in an explicit user clarification, or in a clearly marked open question.
5. Run a critique pass that challenges invented architecture not requested by the brief, missing intent or constraint coverage, unsupported component decisions, and silent expansion of the system boundary.
6. Overwrite the templated stubs with the revised packet and write the provenance sidecar.

Clarification Loop

When the authored input is structurally present but materially ambiguous on points that would force the assistant to invent content, ask targeted clarification questions before generation rather than papering over the gap.

Question Granularity Rules

• One question per question. Never bundle multiple decisions into a single prompt with and, or, or comma-separated sub-questions.
• Each question must isolate exactly one decision the user can answer with one short response.
• If a topic naturally needs several decisions, split it into separate atomic questions and label them as a short series.
• Prefer fixed-choice options when the answer space is small and known.

Question Format (mandatory)

Each question must follow this shape:

- Question: <one-sentence question>
  - Affects: <artifact or section it changes>
  - Why it matters: <one short line on what changes if unanswered>
  - Context: <≤2 lines from authored input, or `no input coverage`>
  - Options:
    a) <concrete option>
    b) <concrete option>
    c) <concrete option>
    d) Other (free-form)
  - Default if skipped: <explicit default>
  - Status: Required | Optional

Use Host UI Affordances When Available

• When the host surface supports rich question UI (selectable options, secondary text, tooltips, hover hints), put the Question line as the main prompt and surface Why it matters and Context as secondary or tooltip text rather than dumping the full block inline.
• Keep the visible question short, ideally under ~100 characters; move background, citations, and rationale into the secondary or tooltip slot.
• Fall back to the plain bulleted block above only when the host has no rich question UI or when the user explicitly asks for it inline.

Batch Size

• Ask 3 to 5 questions per round, never more than 7. If more questions exist, defer the lower-impact ones to a later round.

Interaction Loop

• Ask the batch.
• Wait for user answers.
• Apply answers, regenerate the affected sections, and surface any remaining open questions still required to finish the packet.
• Stop the loop when no Required question is unanswered.

Provenance Sidecar

Write .canon/artifacts/<RUN_ID>/system-shaping/ai-provenance.md describing how the packet was produced. It must include:

• The authored input files that were read.
• The clarification questions that were asked, the user answers received, and any defaults that were applied because the user skipped or deferred a question.
• A Clarification Loop section with: number of questions presented, number of Required questions answered, number of Required questions left unresolved, number of Optional questions answered or deferred, and the number of substantive clarifications that drove material changes per artifact section.
• The critique findings that were addressed and any that were intentionally deferred.
• The generation model or assistant identity that produced the artifact set.

Expected Output Shape

• concise run-start or gated summary
• real run id
• real run state
• direct statement of the system-shaping result when a readable packet exists
• primary artifact path and short excerpt when available
• concrete .canon/artifacts/... paths when Canon emitted them
• next steps pointing to $canon-status, $canon-inspect-artifacts, and $canon-inspect-evidence
• generated content must be written only to Canon-managed run outputs such as .canon/artifacts/<RUN_ID>/system-shaping/ and .canon/artifacts/<RUN_ID>/system-shaping/ai-provenance.md, never back into canon-input/

Failure Handling Guidance

• If .canon/ is missing, point to $canon-init.
• The preflight asks only for the missing slot and must preserve valid ownership fields inside the current interaction.
• If risk, zone, or input are missing, name the missing input, keep the already valid fields, and show the exact Canon CLI retry form after the semantic prompt.
• If preflight returns classification confirmation instead of readiness, treat that as missing intake confirmation rather than as a Canon approval gate.
• If Canon fails because no owner could be resolved, ask for --owner <OWNER> explicitly or tell the user to configure git user.name and git user.email.
• If the brief lacks explicit Intent: or Constraint: markers, ask only for the missing marker rather than discarding the rest of the brief.
• For RISK, use guided fixed choices with the exact allowed values low-impact, bounded-impact, and systemic-impact.
• For ZONE, use guided fixed choices with the exact allowed values green, yellow, and red.
• For SYSTEM_CONTEXT, use guided fixed choices with the exact allowed values new and existing.
• If an input is invalid, tell the user which typed slot failed and retry only that slot.
• If the input file is missing, ask only for the missing path and do not restate already valid ownership metadata.
• If an explicit inline note is empty or whitespace-only, ask only for non-empty --input-text content and do not restate already valid ownership metadata.
• If Canon fails after preflight succeeds, state that the failure happened inside Canon execution rather than before Canon execution.
• If Canon returns Blocked, surface the concrete blocked gate and keep the emitted artifact paths visible for inspection.
• Never emit a fabricated Canon run result.
• If the assistant has already edited or is about to edit an authored input file under canon-input/, stop, restore the file from the user's last saved version, and report the rollback before continuing.

Next-Step Guidance

• When Canon emitted readable artifacts, recommend $canon-inspect-artifacts first.
• When Canon emitted a readable system-shaping result in the run summary, treat that summary as the happy path and keep $canon-inspect-artifacts as drill-down.
• Use $canon-inspect-evidence when the user needs critique lineage or artifact provenance details.
• Use $canon-approve only after the user has reviewed the packet or explicitly wants to record approval.
• After approval, recommend $canon-status first and use $canon-resume only if Canon still leaves the run incomplete.

Related Skills

• $canon-status
• $canon-inspect-artifacts
• $canon-inspect-evidence
• $canon-approve
• $canon-resume