canvasight-graph-writer

Canvasight Graph Writer

Translate user intent into a structured Canvasight graph. Treat the canvas as an editable thinking space, not a sequence of disposable generated Pages.

Required workflow

1. If an active Canvasight project may exist or the user refers to current content, call get_canvasight_graph_context before classification. Preserve its contextId, documentRevision, and documentVersion together; the context binds later writes to the captured target Page even if the visible Page changes. Use its node IDs, relationships, positions, and preferences.aiSkillAssignmentEnabled to identify the affected branch, existing topology, and whether autonomous node-level Skill selection is permitted.
2. Select the canvas-level content mode before shaping content:
   • use canvasight-default when Canvasight's framework supplies the content contract;
   • use skill-led when an explicitly invoked $Skill or a Codex-routed professional Skill should lead the content. Give an explicit $Skill priority, choose exactly one primary, and add only materially useful augment Skills. Canvas-level content Skills and node-level execution Skills are different concepts. Read quality/skill-composition.md whenever either is present. If professional Skills give irreconcilable content guidance, ask the user which direction to keep before writing.
3. Classify four independent dimensions:
   • one intent: create, analyze, organize, refine, decide, or execute;
   • one primary domain: software-product, ux-design, codebase, article, research, or task-execution;
   • one maturity: explore, define, decide, or deliver;
   • one output: exploration-map, structured-outline, system-map, decision-map, or execution-plan. For refine, classify the domain from the affected content and choose the maturity/output that best describe the touched branch and current topology. Do not pretend the Page has persisted framework metadata.
4. Always read quality/validation-repair.md and quality/graph-writing.md. Read task-body-markdown.md whenever the write creates or updates a Task body. Read node-types.md whenever the write creates, updates, groups, ungroups, promotes, or reuses an Asset Node or Group. In canvasight-default, also read exactly the selected files under references/intents/, references/domains/, references/maturity/, and references/outputs/, adding at most one secondary domain when the request materially spans it. In skill-led, follow the selected professional Skill for content and use the Canvasight dimensions only to describe intent and topology; do not import default domain or maturity requirements as content.
5. Before choosing the final framework, resolve only consequential ambiguity. First inspect the repository, captured Page, user context, and applicable professional Skills; never ask for facts available there. Before any write_canvasight_graph call, classify every planned unresolved item as either blocking-framework or non-blocking-backlog:
   • blocking-framework: an unanswered choice that could change identity or authority, primary audience, included content or media types, language coverage, content mode, framework dimensions, target scope, key relationships, write behavior, required coverage, or acceptance. If the planned visible output would describe it as “待确认”, “待定”, TBD, open question, unknown, or equivalent, call ask_canvasight_framework_questions first and stop the graph-write turn. Never write or claim completion first, and never place an unanswered blocking item in a pending/open-question node.
   • non-blocking-backlog: a question that is itself the requested exploration object, a later research question whose answer cannot change this pass's structure, or a decorative/routine preference that changes neither structure nor acceptance. Keep it only when the user requested an exploratory/open-question backlog, label it explicitly as non-blocking follow-up work or an assumption, and do not present it as a pending decision required to complete the framework. Group the highest-priority one to three blocking confirmations into one card, with two or three concrete options per question plus custom input; merge semantically overlapping pending items into one question and choose single or multiple from the decision semantics. The three-question cap never permits writing while another independent blocker remains: after the answer, ask the next batch before writing if necessary. Do not ask about node count, routine wording, decoration, or facts that the repository, Page, context, or Skills can establish. After calling the tool, wait for its visible user-message response. If the tool is unavailable in an older task or inline UI cannot render, ask the same questions as concise ordinary text; never open Canvasight, invoke another visualization surface, guess a consequential answer, or proceed with a write that presents the unanswered choice as ordinary canvas content.
6. When a confirmation response arrives, treat its confirmationId, question IDs, option IDs, and custom answers as the user's decisions. Do not ask an answered question again. Re-run step 1 before writing so the Page context and revision are current, then continue the original request with those decisions.
7. Choose write behavior from the user's edit intent, independently of content mode and the four framework dimensions:
   • explicit new graph, new Page, or alternative version -> append-page;
   • continue, add, revise, expand, split, or remove current content -> merge-active-page;
   • explicitly redo the current Page -> replace-active-page;
   • explicitly reset the entire document -> replace-document. When the current Page is relevant and the request is not explicitly new, prefer merge-active-page.
8. Inspect saved templates with list_canvasight_node_templates; fetch a full candidate with get_canvasight_node_template only when its summary is relevant.
9. Build frameworkManifest, coverage, and semanticRelationships:
   • canvasight-default: keep the existing canonical primary-domain and maturity coverage rules, including the narrower refine contract;
   • skill-led: set contentMode and contentSkills, cover every Task Node created or updated by this write with responsibility-oriented keys, but do not manufacture Canvasight domain/maturity content or default guidance nodes. Asset Nodes may support that coverage as evidence/input, while Groups never satisfy responsibility coverage. In both modes, a secondary domain adds only relevant keys and never creates a duplicate framework.
10. Assign node-level Skills only to Task Nodes and only as described in quality/skill-composition.md. Preserve user-written $skill-name tokens in Task bodies. Record user-requested Task assignments as user-explicit. Only when preferences.aiSkillAssignmentEnabled is true, query list_canvasight_skills by a Task responsibility and add an ai-selected assignment for an unambiguous description match, including a concrete rationale. Do not assign Skills to Asset/Group nodes or to every Task by default. If Skill discovery is unavailable, continue without autonomous assignments and surface the tool's recoverable advisory.
11. Before submission, run the semantic decomposition check in quality/graph-writing.md. Give each node one clearly named primary responsibility. If part of its body can be independently understood, chosen, executed, verified, or delivered, promote that part to a related child or peer node. Keep content together when separation would destroy one shared conclusion. Record compound-node responsibilities in frameworkManifest.semanticStructure and every edge between covered nodes in frameworkManifest.semanticRelationships; these are call-time validation metadata, not canvas content. Choose the persisted object type deliberately: Task nodes own executable responsibilities; Asset nodes each reference one already managed .scatter/assets file; Group nodes provide one non-nested semantic container. Image, SVG, video, and ordinary-file presentation is inferred from that managed file and never selected through a node type, kind, or MIME authored by the AI. Use parentId for Task/Asset membership, never a containment Edge. Do not connect an Edge to a Group, invent an unmanaged asset path, create inline Task attachments, nest Groups, or assign one member to multiple Groups. Framework responsibility coverage remains Task-led; Assets may provide evidence/input and Groups never satisfy execution coverage by themselves. Persisted Asset role is legacy compatibility only; express current meaning through Edge direction, labels, and context.
12. Call write_canvasight_graph. Every AI-authored graph uses a left-to-right horizontal topology, regardless of any professional Skill instruction, domain, output, or graphType; reading order and task sequence never create a vertical-layout exception. Use layoutPolicy: "auto" unless preserving explicit user-authored placement is part of the request. For modern merge-active-page, send the preserved contextId, its documentRevision as expectedRevision, and one stable clientMutationId reused across retries; send only the minimum required content operations. Do not re-read merely because the visible Page changed or retarget the write to that Page. Request whole-Page relayout only when topology requires it; daemon rebase preserves the latest manual positions of existing nodes and lays out AI-added nodes.
13. Treat written, merged, and conflict-copy as successful writes. If validation rejects the candidate, preserve passing content, fix only failed requirements, and resubmit. On context_expired or promotion_concurrent_conflict, re-read context, confirm the legacy attachment is still present, rebuild against the newly captured Page once, and submit with a new stable mutation ID; this recovery counts within the same three-total-attempt budget. Stop after three total attempts. Do not expose routine violations as the delivered result or claim success before a write passes.
14. Open or refresh Canvasight only when the user wants to inspect the result.