BdM-15/capture-insights / skills/proposal-generator
proposal-generator
VerifiedShipley-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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| assets/compliance_matrix.html | other | 2.7 KB |
| assets/compliance_matrix.md | markdown | 1.9 KB |
| assets/executive_summary.md | markdown | 1.1 KB |
| assets/fab_chain.md | markdown | 492 B |
| assets/one_pager.html | other | 1.5 KB |
| assets/slide_master.html | other | 1.9 KB |
| assets/theme_card.html | other | 1.3 KB |
| assets/theme_card.md | markdown | 850 B |
| assets/volume_outline.md | markdown | 653 B |
| evals/evals.json | config | 4.4 KB |
| references/anti_slop_checklist.md | markdown | 1.4 KB |
| references/critique_prompt.md | markdown | 797 B |
| references/govcon_design_tokens.md | markdown | 2.8 KB |
| references/page_budget_heuristics.md | markdown | 798 B |
| references/section_lm_traceability.md | markdown | 753 B |
| references/section_lm_visualization.md | markdown | 1.4 KB |
| references/shipley_glossary.md | markdown | 2.6 KB |
| references/win_theme_patterns.md | markdown | 1.1 KB |
SKILL.md
View on GitHub---
name: proposal-generator
description: 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).
license: MIT
metadata:
title: Proposal Generator
category: pursuit-workspace
status: draft
origin: theseus
invoke: agent
runtime: tools
supports_llm: true
max_turns: 15
output: "pursuits/{slug}/04_proposal/"
upstream: govcon-capture-vibe/.github/skills/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: <verb-led, customer-language phrasing>
DISCRIMINATOR: <what only we can claim>
PROOF POINT: <past_performance_reference name + chunk_id>
GHOST: <competitor weakness — optional>
HOT BUTTON ADDRESSED: <customer_priority entity name>
```
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: <proposal_instruction id>]`
- `[evaluation: <evaluation_factor id>]`
- 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 `<run_dir>/artifacts/` automatically.
3. Invoke huashu-design's PDF renderer via `run_script` with explicit args. The runtime substitutes `{artifacts}` with the absolute path to `<run_dir>/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 <dir> --out <file.pdf> [--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 <md> --output <docx> [--reference <docx>] [--toc] [--metadata KEY=VALUE]` | Pandoc on PATH |
| XLSX | `../renderers/scripts/render_xlsx.py` | `--input <json> --output <xlsx> [--sheet <name>] [--title <text>]` | 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 — <program name>"
],
"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": "<proposal_instruction entity id>",
"instruction_source": "UCF-L | non-UCF | PWS-inline | attachment",
"evaluation_id": "<evaluation_factor entity id>",
"evaluation_source": "UCF-M | non-UCF | adjectival | LPTA",
"requirement_ids": ["<requirement entity id>"],
"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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |