Proposal Pitch

Proposal Pitch Pipeline

Turn a source (chat, issue, or doc) into a reviewable proposal via a configured provider, draft-first: gather the source, agree the page structure with the author before building, render concept stills, publish as drafts only, and close the loop on the source. Invokes the docs-publish surface — the harness docs-publish CLI command (draft, attach-media, verify-render, page-tree) or the docs_publish MCP tool, which resolves a configured connector — for the mechanics, and enforces the gates that keep a pitch honest and safe — drafts-only, render-verify, epistemic labels, and no real customer data.

When to Use

• When turning a chat thread, issue, or design doc into a reviewable proposal published through a configured provider.
• When pitching a concept as a set of draft pages with concept stills for an author to review and later publish.
• When you need the discipline gates (drafts-only, render-verify, epistemic labels, no customer data) wrapped around a publishing flow.
• NOT for the raw publishing mechanics (attachment upload, media forms, render verification) — invoke the docs-publish surface (harness docs-publish <op> / the docs_publish MCP tool), which resolves the configured connector.
• NOT for publishing final/current/live pages — this pipeline is drafts-only; promotion is the author's click.
• NOT when the proposal would require real customer data in a rendered still — that is never permitted (see Gates).
• NOT when the author has not yet agreed the page structure — stop and get agreement first.

Process

Iron Law

Ship drafts, label every claim, and hand back — never resolve the author's open question with your own suggestion, and never publish or expose the work without the author's explicit yes.

A proposal is the author's argument, not the agent's. The agent gathers, structures (with agreement), renders, drafts, and reports — then stops. Publishing, resolving open questions, and public exposure all belong to the author.

Phase 1: GATHER SOURCE

1. Collect the source: the chat thread, the issue, or the doc that the proposal is based on.
2. Separate what is settled (decided, cited) from what is open (unresolved questions, undecided options).
3. Do not invent answers to open items here — record them as open. They travel with the proposal and come back to the author in Phase 5.

Phase 2: AGREE STRUCTURE

1. Draft the proposed page structure: the page tree, the sections, and what each figure will show.
2. Present it to the author and get explicit agreement before building anything. Building against an unagreed structure wastes work and pre-empts the author's framing.
3. If the author has not agreed, do not proceed to render or publish. This is a hard stop (see Gates).

Phase 3: RENDER STILLS

1. Render the concept stills that illustrate the proposal.
2. Invoke the docs-publish surface for the mechanics — deterministic stills, attachment upload, and media forms are the configured connector's responsibility, reached through harness docs-publish attach-media / the docs_publish MCP tool. Do not duplicate that recipe here.
3. Use clearly fabricated fixtures for any data shown in a still. Never use real customer data (see Gates).

Phase 4: PUBLISH DRAFTS

1. Publish the pages as DRAFTS only via the docs-publish surface — harness docs-publish draft / the docs_publish MCP tool (op: draft), and harness docs-publish page-tree for child pages and ordering.
2. For attachments, run harness docs-publish attach-media. Attaching media cannot be automated headless, so the surface returns a manual-step-required result: surface its instructions to the human verbatim, wait for them to complete the upload, then confirm authoritatively (its verifyWith note + verify-render). Do not treat the manual step as done until confirmed.
3. Never move a draft to current/live. Promotion is the author's click.
4. Render-verify every page before handoff via harness docs-publish verify-render / the docs_publish MCP tool (op: verify-render). An unverified page is not done — stored-format correctness is not rendering correctness.

Phase 5: CLOSE THE LOOP

1. Report back on the source (the issue, doc, or chat) with what was built and what remains open.
2. Label every claim on the page and in the report with its epistemic status:
   • verified — you ran or read it; evidence is citable.
   • inferred — drawn from a doc; say which doc, and that it was not re-verified.
   • proposed — invented in this conversation.
3. Carry every open question from Phase 1 back to the author unresolved. The skill's own suggestion never "resolves" an open question — label it proposed and hand it back.
4. Track defects, do not narrate them: fix, file-with-repro, or flag-suspected. "As-designed" requires evidence.

Harness Integration

• harness skill run proposal-pitch / run_skill — invoke this skill.

• harness skill validate proposal-pitch — validate this skill's structure and schema.

• harness docs-publish <op> / docs_publish MCP tool — the publishing surface this pipeline invokes for all mechanics (attachment upload, media forms, page-tree ops, render verification, deterministic stills). The surface resolves a connector configured in harness.config.json (docsPublish block). Do not reimplement those here, and do not name a provider — the surface resolves the connector.

• Config: the connector reads its own provider pointers from its docsPublish.config block in harness.config.json — the pipeline names no provider block. The pipeline itself reads only brand.proposal_css_path for still styling. Documented with placeholder keys only:

  "brand": {
    "proposal_css_path": "<PATH_TO_CSS>"
  }
  

• Absent-config degradation: when no connector is configured (no docsPublish block), or when brand.proposal_css_path is absent, the surface prints a clear message that names what is missing (a docsPublish connector, and/or brand.proposal_css_path) and how to add it. Do NOT crash and do NOT silently no-op.

Success Criteria

• The source is gathered and its settled vs open items are separated.
• The page structure was agreed with the author BEFORE any page was built.
• Concept stills are rendered and render-verified (via harness docs-publish verify-render / the docs_publish MCP tool).
• Pages are published as drafts only — never moved to current/live.
• Every claim carries an epistemic label (verified / inferred / proposed), and no open question was resolved by the skill's own suggestion.
• No real customer data appears in any rendered still.
• The loop is closed: the source is updated with what was built and what remains open.

Examples

Example: chat source → agreed outline → verified draft

1. GATHER SOURCE: read the chat thread. Settled: "the pitch is a two-page proposal with one hero figure." Open: "which pricing tier is the default" — record as open, do not answer.
2. AGREE STRUCTURE: propose a parent page plus one child, with the hero figure on the parent. The author replies "yes, but swap the section order." Update the outline and re-confirm. Only now proceed.
3. RENDER STILLS: build the hero still with a fabricated sample dataset (no real customer names or numbers). Render the still via the docs-publish surface.
4. PUBLISH DRAFTS: create the parent and child as drafts under <PAGE_ID> (the provider's page handle) via harness docs-publish draft / page-tree. If a figure needs an attachment, run harness docs-publish attach-media and hand its manual-step-required instructions to the author, then confirm. Render-verify via harness docs-publish verify-render: media loaded, zero broken-media indicators, the intended figure form matches intent.
5. CLOSE THE LOOP: comment on the source chat — "Built draft parent + child at <PAGE_ID> (draft). Hero figure verified [verified]. Default pricing tier still open [proposed: tier B] — needs your call." Leave the draft-to-current promotion to the author.

Gates

• Drafts only. Publishing is the author's click. Never move a draft to current/live, and never auto-promote.
• Render-verify before handoff. An unverified page is not done. Stored-format correctness is not rendering correctness — run harness docs-publish verify-render (or the docs_publish MCP tool) first.
• Surface every manual step; never fake it. When attach-media returns manual-step-required, hand the instructions to the human and confirm the upload authoritatively (its verifyWith note + render-verify) before calling the page done. Never report an unverified attachment as attached.
• Epistemic labels on every claim. Every claim on the page and in the report is labeled verified / inferred / proposed. The skill's own suggestion NEVER "resolves" an open question.
• Defects tracked, not narrated. Fix, file-with-repro, or flag-suspected. "As-designed" requires evidence — it is not an escape hatch.
• No real customer data in any still, ever. Use clearly fabricated fixtures.
• No public hosting of proposal content without the author's explicit yes. A private draft in the provider is not public exposure; a public URL is — and it requires an explicit yes.

Escalation

• The source has an unresolved open question the author has not answered. Do not resolve it with your own proposal. Label your idea proposed, carry the question back to the author in plain text, and wait.
• A claim cannot be labeled verified / inferred / proposed. Stop. An unlabelable claim is a claim you cannot stand behind — surface it to the author rather than shipping it unlabeled.
• A still would require real customer data to be meaningful. Stop. Propose a fabricated fixture that makes the point, or ask the author how to illustrate it without real data. Never render real customer data.
• The author has not agreed the structure. Do not render or publish. Present the proposed structure and wait for explicit agreement.
• The author asks to publish to current or expose a public URL. Confirm explicitly in plain text before doing either; absent an explicit yes, stay in drafts and keep it private.

Rationalizations to Reject