---
name: bidding-documents
description: "Generate bidding/proposal deliverables: Word design docs + PPT pitch decks. Covers requirements analysis, document structure, python-docx/python-pptx generation, and coordination between deliverables."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [bidding, proposal, Word, docx, PPT, pitch-deck, document-generation]
    related_skills: [powerpoint, ocr-and-documents, officecli]
---

# Bidding & Proposal Document Generation

## When to Use

Use this skill when generating a complete bidding/proposal package — typically a Word design document plus a matching PPT pitch deck. Covers the full workflow from requirements gathering through document generation.

## Workflow

### Phase 1: Requirements Analysis
1. Gather client requirements document (Word/PDF/markdown)
2. Identify: scope (phases), functional modules, feature count, technical constraints
3. Produce a platform/channel integration analysis if relevant (API vs RPA, compliance risks)
4. Confirm ambiguities with client before proceeding — ask specific questions, don't assume

### Phase 2: Word Design Document
Generate a comprehensive technical design document using `python-docx`. Standard structure:

```
1. Project Overview (background, goals, scope, terminology)
2. System Architecture (layered diagram, tech stack, deployment)
3. Detailed Module Design (per-module: workflow, agent design, channel integration)
4. Data Architecture (data flow, closed-loop design, dashboard metrics)
5. Future Phases (brief overview of phase 2/3)
6. Implementation Plan (phases, timeline, milestones)
7. Risk Analysis (risk table with level, description, mitigation)
Appendix (agent inventory, platform integration details)
```

See `references/python-docx-patterns.md` for code patterns and styling recipes.

### Phase 3: PPT Pitch Deck

**Prefer `officecli` for PPT creation** (single binary, visual feedback via `view html`/`watch`, path-based addressing). Fall back to `python-pptx` only for complex programmatic layouts officecli can't express.
Generate a visual pitch deck using `python-pptx`. Standard structure (12-15 slides):

```
1. Cover (project name, subtitle, company, date)
2. Table of Contents
3. Requirements Understanding (scope, challenges)
4. System Architecture (layered visual)
5-7. Core Modules (one slide per major module, with agent cards)
8. Platform Integration (channels table + unified architecture)
9. Data Analytics (closed-loop + dashboard metrics)
10. Future Phases (expansion cards)
11. Implementation Plan (phased timeline + milestones)
12. Risk Management (risk table with mitigations)
13. Competitive Advantages (card grid)
14. Q&A / Thank You
```

Also reference the `powerpoint` skill for design principles (color palettes, typography, layout variety).

### Phase 4: Excel Workload Estimation (工时估算)

Generate a detailed workload estimation spreadsheet using `openpyxl`. Standard structure:

```
Sheet 1: 工时估算（逐级汇总）- 4-level hierarchical breakdown: Task → Function subtotal → Module subtotal → Phase subtotal → Phase-group subtotal → Grand total
Sheet 2: 阶段汇总 - Phase-level summary with percentages
Sheet 3: 里程碑甘特图 - Gantt chart (colored phase bars + ◆ milestone markers + section headers per phase group)
Sheet 4: 团队配置 - Team roles, headcount per phase, responsibilities
```

See `references/openpyxl-workload-patterns.md` for code patterns.

#### Hierarchical Breakdown (4 levels)

Every estimate MUST use this structure:
1. **Phase** — Major project phase (e.g., "P1 基础架构", "P2 核心功能")
2. **Module** — Functional modules within each phase
3. **Function** — Feature groups within each module
4. **Task** — Individual work items with person-day estimates

Each task records: Design days, Development days, Testing days, Deployment days, and Notes/dependencies. Subtotals are accumulated at each level in the hierarchy.

#### Multi-Phase Projects

- Each phase needs separate schedule and Gantt section
- Phase groups (e.g., "一期合计", "二期合计") with their own subtotal rows and visual separation (different Gantt bar colors)
- Clear visual separation between phases using section headers and different accent colors
- Dependencies between phases must be documented
- Reusable components from earlier phases should be noted

#### Critical: Scope Completeness Check

Before generating the estimation, verify ALL modules are accounted for. Common hidden modules that get missed:

- **Platform/media management** (账号管理): When a project involves N platforms, account CRUD, credential security (OAuth/Cookie/API Key/Vault), health monitoring, adapter layer, and content format conversion is a large module — often 80-120+ person-days. Do NOT skip it.
- **Integration layer**: Unified publisher/crawler interfaces, adapter registration mechanism
- **Compliance/audit**: Logging, data protection, regulatory compliance

**User feedback signal**: If a reviewer says "XX是个大人物" (XX is a big deal), they mean the module should have been obvious from requirements. This is a SIGNIFICANT ERROR, not a minor omission. Treat with urgency.

#### Team Configuration Sheet

Include a separate sheet with:
- Role names, headcount, which phases they participate in, responsibilities
- Team size per phase group (e.g., "一期团队（7~8人）", "二期团队（6~7人）")
- Section headers with phase-appropriate colors

#### Validation Checklist (Workload Estimation)

Before delivering workload estimation:
- [ ] ALL major modules included (especially infrastructure/platform management)
- [ ] Design+Dev+Test+Deploy breakdown for every task
- [ ] Subtotals at function/module/phase/phase-group levels
- [ ] Gantt chart with week ranges and milestone markers
- [ ] Team configuration with phase participation
- [ ] Critical path identified
- [ ] Dependencies between phases documented
- [ ] File size reasonable (< 100KB for typical projects)

### Coordination Rules
- **Content consistency**: Word doc is the source of truth; PPT summarizes it visually; Excel derives phases/modules from both
- **Same terminology**: Agent names, module names, platform names must match exactly across all three deliverables
- **Placeholder markers**: Use `[Company Name]`, `[Contact]` placeholders — never hardcode
- **Generation order**: Word first (captures full detail), PPT second (summarizes), Excel third (quantifies)

## Business-Facing (Client Communication) Mode

When the deliverable is for the client's *business* people (not their tech team), it is a DIFFERENT document than the technical design doc. Two modes coexist:

| | Technical design doc | 业务沟通方案 (client-facing) |
|---|---|---|
| Audience | client engineers / PMs | client business & management |
| Focus | HOW (architecture, modules, tech) | WHAT value, WHAT pain, WHAT process |
| Jargon | fine | **strip it** |

**Jargon translation discipline** (apply aggressively in client-facing mode):
- Agent / LLM → 「智能环节」「自动化」 (never name the tech)
- RAG / 向量库 → 「智能检索」
- 知识图谱 → 「关联关系检索」
- Do not mention model names, vector DBs, or internal product names the client wouldn't know.

**Tone & style**: use 「贵方」 for the client, polite proposal (建议书) tone. Finance/institutional clients → deep-navy + gold palette reads professional and conservative.

## Phase 5: Quality Evaluation Against Requirements

Before delivering, systematically verify the docs actually cover the source requirements — this catches real gaps a draft always has. Compare against the requirement files dimension by dimension:

1. **需求覆盖度** — does every requirement scenario get its own expanded treatment (not a one-line mention)? A requirement listed as one of "N core scenarios" but given only one bullet is UNDER-COVERED — expand it.
2. **业务准确性** — is the domain terminology correct, and do you carry over the *business insight* (判断标准 / 核心评估建议), not just headings? Listing section titles without the underlying risk-judgment logic is shallow.
3. **业务导向性** — is technical jargon stripped for the target audience?
4. **结构逻辑性** — internal consistency: does the overview's count of capabilities match the detailed list? (e.g. overview says "5 capabilities" but detail shows 8 — the reader can't reconcile them.)
5. **完整性与深度** — are the requirement's "key value propositions" (e.g. a report's stated core purpose/作用) reflected back in the value section, or does the value section talk about something else?
6. **后续工作建议呼应** — if the requirement doc closes with a "后续工作建议" (proposed next-steps, e.g. 现场调研 → 需求细化 → 方案设计 → 原型验证), the proposal's own closing MUST explicitly affirm that rhythm ("我们认同贵方提出的四步推进建议，愿先现场调研…"), not offer a generic "pilot then roll out". Echoing the client's own stated process signals careful reading and alignment with how they want to proceed.

Write the evaluation as a scored report (per-dimension + overall), list gaps by severity (必改 vs 建议改), then revise. A client-facing doc whose value section doesn't mirror the requirement's own framing of "what this report is FOR" will read as tone-deaf.

## Pitfalls

- **Don't skip platform management module**: When a project involves multi-platform publishing/collection (10+ platforms), ALWAYS include a dedicated "媒体平台管理" or "Platform Management" module covering: account CRUD, credential security (OAuth tokens, Cookie/Session, Vault encryption, auto-refresh), platform-specific configuration (content specs, rate limits, audit rules), health monitoring (liveness detection, login state, API quota, auto-recovery), and a unified adapter layer (Publisher/Crawler interfaces). This is typically 80-120+ person-days — missing it causes massive underestimation.
- **Don't skip platform analysis**: For projects involving multi-platform publishing or data collection, produce a detailed integration analysis BEFORE writing the design doc. It informs the technical architecture.
- **openpyxl merged cell write order**: In openpyxl, you MUST write to the top-left cell BEFORE calling `merge_cells()`. Writing to a merged cell after merging raises `AttributeError: 'MergedCell' object attribute 'value' is read-only`. Pattern: `cell(ws, r, c, value)` → `ws.merge_cells(...)` — never the reverse.
- **Don't invent technical details**: If a platform's API/RPA approach is uncertain, mark it as "待确认" (to be confirmed) rather than guessing.
- **Don't over-promise in PPT**: PPT should reflect what's actually designed in the Word doc, not aspirational claims.
- **Word tables need style**: Always pass `style='Light Grid Accent 1'` or similar to `add_table()` — raw tables look unprofessional.
- **Chinese font fallback**: Set `font.name = '微软雅黑'` for all text when generating Chinese documents; python-docx doesn't handle CJK fallback well.
- **Page breaks between chapters**: Always `doc.add_page_break()` before major sections to keep the Word doc clean.
- **PPT color theme**: Define color constants at the top of the script and reuse throughout. Never hardcode RGBColor inline — it leads to inconsistency.
- **Excel freeze panes**: Always set `ws.freeze_panes = 'A2'` on data sheets and `'D2'` on gantt sheets so headers stay visible when scrolling.

## Dependencies

```bash
pip install python-docx python-pptx
```

Both are pure Python, no system dependencies.

**Node alternative** (used for Chinese client decks/word docs): `npm install pptxgenjs docx`. pptxgenjs (pptxgenjs) + docx-js (`require('docx')`) are good when you want a single JS script per deliverable. Chinese text needs `fontFace: "Microsoft YaHei"` on every text run (pptxgenjs) and a run-level `font: "Microsoft YaHei"` (docx-js). docx-js tables still need dual widths: `columnWidths` on the table AND `width` (DXA) on every cell.