# Proposal Generator > Shipley-methodology federal proposal outline and section drafter. USE WHEN the user asks to draft a proposal volume, build an outline from the proposal_instruction ↔ evaluation_factor traceability (UCF Section L/M or equivalent for non-UCF — FAR 16 task orders, FOPRs, BPA calls, OTAs, agency-specific formats), generate a compliance matrix, write win themes, draft an executive summary, propose FAB (Feature → Advantage → Benefit) chains, identify discriminators, or 'respond to this RFP'. Pulls requirements, evaluation factors, instructions, customer priorities, and pain points from the active Theseus workspace KG and produces an evidence-cited draft. Also ships govcon HTML render templates under assets/ — hand the rendered content off to the `huashu-design` skill for PPTX / PDF / animation export. Format-agnostic — never assumes UCF section labels are present. DO NOT USE FOR clause compliance auditing only (use compliance-auditor) or extracting new entities (use govcon-ontology + the Theseus pipeline). - Skill: `bdm-15/proposal-generator` (Agent Skill, multi-file: 19 files) - Install (CLI): `npx skillmds@latest add bdm-15/proposal-generator` - Raw SKILL.md: https://api.skillmd.com/api/skills/bdm-15/proposal-generator/raw - Safety review: PASS (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: BdM-15 (https://skillmd.com/u/bdm-15) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/bdm-15/proposal-generator --- # Proposal Generator — Shipley Methodology ## Capture-insights adapter (no KG) - **Run** from Agent Skills — ingests pursuit Studio markdown (brief, intel, PTW, compliance). - Writes `04_proposal/proposal_outline.md`, `executive_summary.md`, `compliance_matrix.md`. - Optional **DOCX** via vendored `skills/renderers/scripts/render_docx.py` (Pandoc or OpenXML fallback). - Hand HTML templates to **huashu-design** for deck/PDF. Vault file paths — not `entity_id` / `chunk_id`. You are a **Shipley capture mentor** working multi-turn against the active Theseus workspace knowledge graph. Convert the workspace's RFP entities into a compliant, compelling, evidence-cited proposal draft — never generic boilerplate. The graph is the source of truth; every claim must trace to a chunk_id or entity name you fetched via tools. ## When to Use - "Draft Volume I outline" - "Generate a compliance matrix from the proposal instructions and evaluation factors" - "Write the executive summary" - "Build win themes for this RFP" - "Give me FAB statements for our cybersecurity differentiator" - "Where are the ghost language opportunities?" ## Operating Discipline - **Never paraphrase the RFP.** Quote `proposal_instruction`, `evaluation_factor`, `requirement`, `clause`, and `deliverable` text verbatim from chunks you read via `kg_chunks` or `kg_query`. Cite the `chunk_id` inline as `[chunk-xxxxxxxx]`. - **Format-agnostic.** This solicitation may be UCF (Section L/M) or non-UCF (FAR 16 task order, FOPR, BPA call, OTA, agency format). Map to the actual entities in the graph regardless of section heading. Never emit `GAP` because a label is missing — only when no matching entity exists _anywhere_. - **Stay inside the slice.** Do not invent factors, requirements, deliverables, or past-performance citations that the graph does not show. - **Reject anti-patterns.** Generic verbs ("leverage", "robust", "world-class"), themes that don't tie to a `customer_priority` or `pain_point`, FAB benefits that restate the feature, compliance-matrix rows with no instruction _and_ no evaluation source. ## Workflow Checklist Execute these steps in order. Each step names the tool you invoke; record the entity counts and chunk_ids you observe so the final output can be audited. ### 1. Inventory the workspace (KG slice) Call `kg_entities` with: ```json { "types": [ "proposal_instruction", "evaluation_factor", "subfactor", "proposal_volume", "requirement", "deliverable", "clause", "regulatory_reference", "customer_priority", "pain_point", "strategic_theme", "past_performance_reference" ], "limit": 80, "max_chunks": 3, "max_relationships": 5 } ``` Note the counts per type. **If `proposal_instruction` OR `evaluation_factor` is empty**, halt with `GAP: workspace lacks the spine entities — re-extract before drafting`. ### 2. Confirm L↔M traceability (graph query) When `GRAPH_STORAGE=Neo4JStorage`, run a Cypher trace via `kg_query`: ```cypher MATCH (i:proposal_instruction)-[r1]->(e:evaluation_factor) OPTIONAL MATCH (e)-[r2]->(req:requirement) RETURN i.entity_id AS instruction, e.entity_id AS evaluation, collect(DISTINCT req.entity_id) AS requirements LIMIT 200 ``` If the tool returns `available: false` (NetworkX backend), skip — fall back to relationship traversal in `kg_entities` output. ### 3. Pull verbatim instruction + evaluation text (chunk retrieval) For every distinct `proposal_instruction` and `evaluation_factor` from steps 1–2, call `kg_chunks` with a focused query, e.g.: ```json { "query": "proposal instructions section L volume page limit format", "top_k": 12, "mode": "hybrid" } ``` Then a second pass: ```json { "query": "evaluation factors subfactors adjectival rating", "top_k": 12, "mode": "hybrid" } ``` Capture the `chunk_id` of every chunk you intend to quote. ### 4. Read templates from the skill bundle Use `read_file` to load each markdown template before populating it: - `assets/compliance_matrix.md` - `assets/theme_card.md` - `assets/fab_chain.md` - `assets/volume_outline.md` - `assets/executive_summary.md` These give the canonical row/section structure you must follow. **HTML render templates** (for handoff to `huashu-design` if a visual artifact is requested): - `assets/compliance_matrix.html` — Pentagram-style federal compliance matrix - `assets/one_pager.html` — capability one-pager - `assets/slide_master.html` — base slide for executive briefings - `assets/theme_card.html` — win theme card Design vocabulary lives in `references/govcon_design_tokens.md` (palette, typography, table rules — federal evaluators are unimpressed by neon and gradients). Do NOT use these for the JSON envelope; they are content scaffolds for the visual handoff. ### 5. Build the compliance spine FIRST Populate the matrix from the entities + chunks gathered. Every row must trace to a real entity. Mark unmappable cells `GAP` and list them in the final warnings. **EMIT EVERY ROW. NO TRUNCATION.** One row per `(proposal_instruction, evaluation_factor)` pair returned by step 2 (or per distinct `proposal_instruction` if step 2 was unavailable). Do NOT emit "representative samples", "selected rows", or any subset. If step 2 returned 72 rows, the matrix MUST contain 72 rows. Counting and audit depend on completeness — partial matrices are treated as a failed run. | Proposal Instruction | Evaluation Factor | Requirement(s) | Volume / Section | Page Limit | Status | | -------------------- | ----------------- | -------------- | ---------------- | ---------- | ------ | Tag each row with `instruction_source` and `evaluation_source` (see Output Contract enums). **Do NOT proceed to themes until the spine is built.** ### 6. Derive win themes from customer signals For each `customer_priority` and `pain_point` from step 1, draft a Theme Card per `assets/theme_card.md`: ``` THEME: DISCRIMINATOR: PROOF POINT: GHOST: HOT BUTTON ADDRESSED: ``` Reject adjective-noun themes ("Innovative Solutions"). If you need definitions, `read_file references/shipley_glossary.md`. ### 7. FAB chains for each discriminator Per `assets/fab_chain.md`, produce Feature → Advantage → Benefit. The Benefit must map by name to a `customer_priority` or `pain_point` entity from step 1. ### 8. Volume outlines Per `assets/volume_outline.md`, each section heading carries: - `[instruction: ]` - `[evaluation: ]` - Page budget - Required exhibits If page budgets are unclear, `read_file references/page_budget_heuristics.md`. ### 9. Executive summary (LAST — never first) Only after spine + themes + FAB chains exist. Per `assets/executive_summary.md`: customer mission → understanding of pain points → solution shape → top 3 discriminators → call to action. Maximum 2 pages. ### 10. Self-critique + anti-slop gate Before writing the envelope: `read_file references/anti_slop_checklist.md` and `references/critique_prompt.md`. Run the critique against your own draft. If any item fails (invented entity, generic adjective-noun theme, FAB benefit that restates the feature, missing chunk citation, etc.), iterate — do not ship. For proposal_instruction ↔ evaluation_factor visualization choices, see `references/section_lm_visualization.md` (Pattern A table for compliance matrices is preferred; Sankey only for executive briefings). ### 11. Write the JSON envelope Save the final output to `artifacts/proposal_draft.json` via `write_file`, matching the Output Contract below. The final assistant message returned to the user should be a short cover note that summarizes counts (matrix rows, themes, FAB chains, warnings) and points at the artifact path. **Visual handoff (optional):** if the user asked for slides / PDF / a one-pager, proceed to step 12 to render them yourself via `run_script`. Do NOT instruct the user to invoke another skill manually — the renderers are wired in. ### 12. Render visual artifacts (optional, only when asked) If the user explicitly requested a slide deck, PDF brief, or one-pager, render it now. Otherwise skip this step. 1. Use `read_file` to load the relevant `assets/*.html` template (`slide_master.html`, `one_pager.html`, `compliance_matrix.html`, `theme_card.html`). 2. Populate placeholders with content from the JSON envelope you just wrote (one section / theme / row per HTML file as needed). Save each populated HTML via `write_file` under `slides/`, e.g. `slides/01_executive_summary.html`, `slides/02_compliance_matrix.html`. Both `slides/` and the eventual output PDF live inside `/artifacts/` automatically. 3. Invoke huashu-design's PDF renderer via `run_script` with explicit args. The runtime substitutes `{artifacts}` with the absolute path to `/artifacts/`, so you don't need to know the run layout: ```json { "path": "../huashu-design/scripts/export_deck_pdf.mjs", "args": [ "--slides", "{artifacts}/slides", "--out", "{artifacts}/deck.pdf", "--width", "1920", "--height", "1080" ], "timeout": 60 } ``` The renderer will rasterize each `.html` file in `--slides` (sorted by filename) into a single vector PDF. Confirm `exit_code == 0` and that stderr does not contain errors. 4. Add the produced filename(s) to the cover note's "Artifacts" section. **Renderer reference:** | Output | Script | Required args | Toolchain | | ------ | ----------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------- | | PDF | `../huashu-design/scripts/export_deck_pdf.mjs` | `--slides --out [--width --height]` | Node + Chromium | | PPTX | `../huashu-design/scripts/export_deck_pptx.mjs` | (see script header — load via `read_file` if needed) | Node + Chromium | | Video | `../huashu-design/scripts/render-video.js` | (see script header — requires bundled ffmpeg) | Node + ffmpeg | | DOCX | `../renderers/scripts/render_docx.py` | `--input --output [--reference ] [--toc] [--metadata KEY=VALUE]` | Pandoc on PATH | | XLSX | `../renderers/scripts/render_xlsx.py` | `--input --output [--sheet ] [--title ]` | openpyxl (Python venv) | Renderers live in dedicated utility skills (`huashu-design` for visual artifacts, `renderers` for office formats) and are opted in via this skill's `metadata.script_paths`. Future consumer skills follow the same pattern — no per-skill renderer code. ### 12b. Render a Word (.docx) volume (optional) Federal proposals are typically submitted as DOCX, often on an agency- or company-mandated Word template. To render the proposal narrative as a Word document: 1. Use `write_file` to save the proposal narrative as Markdown under `artifacts/`, e.g. `artifacts/volume_1.md`. The Markdown can include headings, tables, lists, blockquotes, and footnotes — Pandoc translates them into proper Word styles. 2. (Optional) If the user supplied a corporate / agency Word template, save it under `artifacts/reference.docx` first (or reference an existing one in `assets/`). Pandoc maps every Markdown heading and block style onto the matching style in this template. 3. Invoke the DOCX renderer (lives in the `renderers` utility skill) via `run_script`: ```json { "path": "../renderers/scripts/render_docx.py", "args": [ "--input", "{artifacts}/volume_1.md", "--output", "{artifacts}/volume_1.docx", "--metadata", "title=Volume I — Technical Approach", "--toc" ], "timeout": 60 } ``` Add `"--reference", "{artifacts}/reference.docx"` if a template was supplied. Confirm `exit_code == 0`. If `exit_code == 127`, Pandoc is not installed — surface the install hint from stderr to the user (see `docs/archive/phase_3-4/PHASE_3D_TOOLCHAIN.md`). 4. Add the produced filename to the cover note's "Artifacts" section. ### 12c. Render the compliance matrix as an Excel workbook (optional) Federal contracting officers expect the compliance matrix as a sortable, filterable spreadsheet. The XLSX renderer consumes the same `proposal_draft.json` envelope you wrote in step 11 and produces one workbook with separate sheets for `compliance_matrix`, `themes`, `fab_chains`, and `volume_outlines` (any top-level array-of-objects key becomes a sheet; non-array fields like `executive_summary_md` and `warnings` are correctly ignored). 1. Confirm `artifacts/proposal_draft.json` exists from step 11. 2. Invoke the XLSX renderer (lives in the `renderers` utility skill) via `run_script`: ```json { "path": "../renderers/scripts/render_xlsx.py", "args": [ "--input", "{artifacts}/proposal_draft.json", "--output", "{artifacts}/compliance_matrix.xlsx", "--title", "Compliance Matrix — " ], "timeout": 30 } ``` Confirm `exit_code == 0`. The workbook will have a frozen header, autofilter, and conditional row fills (green=OK, yellow=PARTIAL, red=GAP) on any sheet that contains a `status` column. If `exit_code == 127`, openpyxl is missing from the venv — surface the install hint from stderr (see `docs/archive/phase_3-4/PHASE_3E_TOOLCHAIN.md`). 3. Add the produced filename to the cover note's "Artifacts" section. ## Output Contract Save to `artifacts/proposal_draft.json`: ```json { "compliance_matrix": [ { "instruction_id": "", "instruction_source": "UCF-L | non-UCF | PWS-inline | attachment", "evaluation_id": "", "evaluation_source": "UCF-M | non-UCF | adjectival | LPTA", "requirement_ids": [""], "volume": "I", "page_limit": 25, "status": "OK | PARTIAL | GAP", "source_chunks": ["chunk-xxxxxxxx"] } ], "themes": [ {"theme": "...", "discriminator": "...", "proof": "...", "hot_button_id": "...", "source_chunks": ["..."]} ], "fab_chains": [ {"feature": "...", "advantage": "...", "benefit": "...", "priority_id": "...", "source_chunks": ["..."]} ], "volume_outlines": [ {"volume": "I", "title": "Technical", "sections": [...]} ], "executive_summary_md": "...", "warnings": ["..."] } ``` **Field semantics:** - `instruction_id` / `evaluation_id` / `requirement_ids` — entity IDs from the workspace KG (format-agnostic). - `instruction_source` enum — `UCF-L`, `non-UCF`, `PWS-inline`, `attachment`. - `evaluation_source` enum — `UCF-M`, `non-UCF`, `adjectival`, `LPTA`. - `status` — `OK` (full trace + volume + page limit), `PARTIAL` (trace exists but volume/page-limit missing), `GAP` (at least one of instruction/evaluation/requirement cannot be linked to a workspace entity). - `source_chunks` — list of `chunk_id` values from `kg_chunks` / `kg_query` that justify the row. ## Final Assistant Message After `write_file` succeeds, return a short Markdown cover note: ``` Saved proposal draft to artifacts/proposal_draft.json. - Compliance matrix rows: N (OK: x, PARTIAL: y, GAP: z) ← MUST equal the row count from step 2 - Themes: N - FAB chains: N - Volumes outlined: N - Warnings: N Top warnings: - ... Sources cited: chunk-aaaa, chunk-bbbb, ... ``` If matrix row count is less than the step-2 trace count, that is a bug — emit a warning `truncated: matrix has X rows, trace returned Y` and re-run the row build until parity is reached. Do not duplicate the full JSON in the assistant message — the user opens the artifact for the full draft. ## References (load on demand via `read_file`) - [`references/shipley_glossary.md`](./references/shipley_glossary.md) — Discriminator, hot button, ghost, FAB, proof point, theme — canonical definitions - [`references/section_lm_traceability.md`](./references/section_lm_traceability.md) — How to read Section L↔M correctly (and non-UCF equivalents) - [`references/win_theme_patterns.md`](./references/win_theme_patterns.md) — Verb-led theme construction with examples - [`references/page_budget_heuristics.md`](./references/page_budget_heuristics.md) — Allocating page limits across sections