Qv Qip Create

QIP Proposal Create

Help an author produce a concise architectural decision brief for Slack Canvas. It tells stakeholders why a decision is needed, what direction is proposed, where it fits in the architecture, and which important trade-offs they must accept. Keep the main proposal focused on that decision; place useful supporting detail in an optional Appendix.

Use qv-qip-triage to decide whether a QIP is needed and qv-qip-review to assess an existing draft.

Ground the proposal

Before drafting:

1. Read references/qip-template.md.
2. Read docs/architecture/PRINCIPLES.md.
3. When the proposal affects public SDK API, native bindings, runtime, mobile support, storage, transport, model registry, release flow, or security boundaries, inspect the relevant current docs or code. Establish the current behavior and proposed architectural delta.

Do not draft from general knowledge alone. Ground substantive claims in user-provided context, repository sources, or clearly labeled assumptions. Prefer questions over assumptions; when a first pass needs assumptions, label them so the author can confirm or remove them. Do not invent motivations, commitments, supported platforms, release plans, security or performance properties, or ownership decisions.

Investigation may be extensive; publication should not be. Use research to validate and compress the QIP rather than reproducing it.

Intake and readiness

Ask only for missing decision context, one question at a time unless the user requests a batch. For a terse or fuzzy idea, ask about the next unanswered readiness item below rather than jumping directly to a draft. Skip questions when the brief already satisfies the readiness gate or the user requests a first pass with assumptions.

A QIP is ready to draft when these are known:

• problem and why a decision is needed now;
• affected architectural or product surface, current behavior, and the proposed change;
• one recommended direction and the exact approval ask;
• at least one credible alternative and why the recommendation is preferable;
• decision-driving benefits, costs, new responsibilities, and failure modes;
• relevant trust-boundary, compatibility, migration, or release impact;
• likely out-of-scope areas when readers could reasonably assume they are included.

A technology list, package name, or desired outcome without this context is a fuzzy idea. Help the author shape it, but do not choose the primary motivation or direction for them. If no direction is ready to recommend, continue discovery or explain what is missing; do not label an option survey as an approval-ready QIP.

Stop and ask rather than draft when the primary motivation, recommended direction, material impact, or accepted trade-off remains unresolved or would have to be inferred.

Draft contract

• Target 600-900 words of core proposal content and treat 1,200 words as a soft ceiling, excluding the approvers table and Appendix.
• Write at the architectural level: responsibilities, boundaries, interactions, and constraints that could change approval.
• Explain why the chosen direction is preferable to the most credible alternative.
• When transport, RPC, storage, authentication, sandboxing, plugin execution, model provenance, or another cross-process or cross-peer trust boundary changes, state the architectural security properties explicitly.
• Call out observable behavior, public API or install-contract changes, migration needs, and expected release or versioning impact when they could affect approval. If an unchanged dimension is likely to concern reviewers, address it in one sentence rather than adding a boilerplate section.
• Prefer a compact diagram in the Solution when it explains responsibilities, trust boundaries, interactions, or state flow more clearly than prose. Keep prose for the decision and trade-offs, and omit a diagram that would merely repeat them. Link it or use a normal image reference; never embed base64 image data.
• Move useful API sketches, protocols, failure-mode analysis, rollout notes, test strategy, phase breakdowns, and larger comparisons to an Appendix in the same QIP unless the detail is itself the decision. Omit file-level change lists unless they provide meaningful evidence.
• Link external artifacts such as PoC PRs, source research, or separately maintained specifications from the Appendix and summarize why they matter; do not copy their full content.
• Never claim human approval.

Before keeping a paragraph in the core proposal, ask whether it helps a reviewer approve, reject, or reshape the direction. Before requiring more detail, ask whether its absence could materially change the recommendation or make approval irresponsible. Otherwise remove it, move useful supporting detail to the Appendix, or defer it explicitly. Keep the Appendix relevant and organized; use a separate technical document only when the material has an independent lifecycle or is too large for the QIP.