sample-driven-report-writing
Analyzes a deliverable sample (PDF/DOCX/Markdown) to extract its table-of-contents structure AND, for each section, whether tables and/or charts are mandatory — then researches and drafts report content that matches the sample's exact structure and visual-element requirements. Use when: writing any consulting deliverable that must conform to a supplied sample or government/institutional template format.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- sample-driven-report-writing
- owner
- communications-lead
- scope
- co-consult
- status
- active
- version
- 1.1.0
- metadata
- { "type": "domain", "triggers": [ "sample-driven report", "deliverable template", "match sample structure", "write to sample format" ] }
- description
- Analyzes a deliverable sample (PDF/DOCX/Markdown) to extract its table-of-contents structure AND, for each section, whether tables and/or charts are mandatory — then researches and drafts report content that matches the sample's exact structure and visual-element requirements. Use when: writing any consulting deliverable that must conform to a supplied sample or government/institutional template format.
- last_reviewed
- 1793923200000
- prerequisites
- consulting-report-writing
03 SKILL.md 正文
Context
This skill generalizes the "write-to-sample" discipline: given a finished reference deliverable (a sample) or an official template form, produce a new deliverable whose chapter structure, section composition, and visual-element usage (tables/charts) match the sample exactly — not approximately.
It replaces engagement-specific hardcoding (a fixed chapter table, a fixed page budget, a fixed team roster) with a sample-analysis procedure that derives all of those from the actual sample on disk. Always re-extract from the real attached sample; never trust a cached or previously-known structure, because template forms are revised (e.g. annual 2026형 → 2027형 editions change chapter counts and required tables).
PM Gateway applies: PM displays an execution plan table before dispatching any specialist at each phase transition. PM may Write/Edit only memory/*.md and CHANGELOG.md directly; deliverable files are produced by dispatched specialists.
When to Use
- A client or engagement lead supplies a reference deliverable (or a government/institutional form template) and the new report must match its structure and format
- A public-sector submission (a results/report template that specifies chapter count, mandatory tables, and page budget) must be filled in
- A completed past deliverable should serve as the structural model for a new engagement
- Do NOT use for free-form reports with no required structure — use
consulting-report-writingalone
Execution Steps
- Phase 1 — Sample Analysis: Ingest the reference deliverable, extract its structure (TOC, mandatory tables/charts per section, placeholder slots, page budget), and produce a Writing Spec artifact. Confirm the spec with the engagement lead before proceeding.
- Phase 2 — Research: Dispatch analytical inputs (financial, legal, industry) mapped to each chapter per the Writing Spec.
- Phase 3 — Draft: Assign chapter owners by content type, draft in parallel against the Writing Spec, replace all placeholders, enforce table-to-narrative ratio and mandatory visual elements.
- Phase 4 — Validate & Render: Structural validation, visual-element audit, render the draft as
.docx/.pdf; any other client-required format is produced outside the workspace from the Markdown draft. Max 2 revision cycles before PM escalation.
Detailed instructions for each phase are below.
Phase 1 — Sample Analysis (the differentiator)
Ingest the actual sample and produce a Writing Spec artifact (memory/<engagement>-writing-spec-<date>.md). This is the single source of truth for the rest of the workflow.
1.1 Ingest the sample
| Sample format | Tool | Notes |
|---|---|---|
.pdf |
md-to-ooxml text extraction / WebFetch / manual read |
If image-only PDF, OCR first |
.docx |
md-to-ooxml / md-to-report reader |
|
| Other formats (e.g. Korean office formats) | Not processed in the workspace — convert to PDF/DOCX/Markdown outside the workspace first |
If only a paper/PDF scan exists, ask the engagement lead for the editable source — analysis fidelity drops sharply on scans.
1.2 Extract the structure and the per-section visual-element requirements
For each chapter/section visible in the sample, record in the Writing Spec:
- Chapter/section number and title (English + original-language).
- Table-of-contents position and approximate page span in the sample.
- Table mandatory-flag: count table markers in that section (
표 N-N,<table>, pipe-tables). If the sample contains one or more tables in this section, mark itrequires-table. Record the typical column structure. - Chart/figure mandatory-flag: count figure/chart markers (
그림 N-N,차트,그래프, embedded images). Markrequires-chartwhere present. Record the chart type (trend line, bar, pie, etc.). - Narrative-only sections: sections with neither table nor chart markers — prose is the expected output.
- Placeholder/guideline slots: every guideline-instruction block (
[작성 가이드라인],[기재 방향],예시N)) and example block that the sample/template uses to instruct the author. These MUST be replaced with real content in the draft — list them so none survive. - Page-budget target: from the sample's completed length (or the template's stated budget), derive a per-chapter page target.
Critical: the table/chart mandatory-flags are not decorative — a section marked requires-table is incomplete without a table, and requires-chart is incomplete without a chart. The draft cannot be considered done until every mandatory visual element is present.
1.3 Confirm the spec with the engagement lead
Before research begins, confirm the Writing Spec (structure + mandatory visual elements + page budget) with the engagement lead. Template editions drift; a wrong spec wastes an entire drafting cycle.
Phase 2 — Research
Dispatch analytical inputs against the Writing Spec's section list:
- Company financials / industry data →
k-dart,financial-statement-analysispipeline (bun scripts/co-consult/financial-pipeline.ts),company-intelligence,competitive-intelligence - Legal / regulatory environment →
k-law - Disclosure fallback (non-disclosing / unlisted target companies with no KR-profile DART filing): use company-provided source documents (
세무조정계산서,결산서,시산표), explicitly labeled기업 제공 비공식 자료with document name and date — these are not independently verifiable the way a DART filing is. - Each research output is mapped to the specific chapter(s) it feeds, per the Writing Spec.
Phase 3 — Draft (parallel, against the Writing Spec)
- PM/Communications Lead assigns chapters per the ownership implied by content type (financial →
data-analyst; narrative →communications-lead; domain →sme; strategy →strategy-analyst). Dispatch chapter owners in parallel — disjoint chapters with Phase-1 research already in hand can be drafted concurrently. - Each owner drafts their chapters in Markdown, replacing every guideline/placeholder slot listed in the Writing Spec with real content.
- Enforce the table-to-narrative ratio: every data table is followed by at least half a page of interpretation. A table alone does not satisfy a section.
- For every section marked
requires-table/requires-chart, the drafted section MUST contain that visual element (Markdown table / Mermaid or chart-spec block). - Communications Lead assembles the full draft, edits for voice/terminology/MECE consistency, and confirms chapter order matches the Writing Spec's TOC exactly.
Phase 4 — Validate & Render
- Structural validation: chapter order matches the sample TOC; no guideline/example placeholder leftovers survive; per-chapter page count is within ±15% of the Writing Spec page budget.
- Visual-element audit: re-scan the draft for each section's mandatory-flag — every
requires-table/requires-chartsection must contain its element. This is the check most likely to fail; iterate. - Render the final format:
- Deliverables are drafted in Markdown.
.docx/.pdf(internal/client review) →bun scripts/co-consult/md-to-report.ts <draft.md>(LibreOffice-backed PDF). - If the client requires another format (e.g. a Korean office format), the Markdown draft is converted to that format outside the workspace; the workspace does not produce or validate it.
- Deliverables are drafted in Markdown.
- Max 2 revision cycles before PM escalation.
Writing Principles (preserved)
- No placeholder leftovers — every guideline/example block in the sample must become real narrative.
- Expand through argument density, not appendices — meet page targets by deepening tables/charts/interpretation, never by padding with raw source documents.
- Table-to-narrative ratio — every table earns at least half a page of interpretation.
- Disclosure fallback (KR profile: DART) — explicitly label company-provided unofficial materials.
- Client-data handling — drafts contain financials and PII; review for sensitive data before any
git add/commit. - File naming —
{company}-{report-type}-{YYYY-MM-DD}_ko.md(draft) →.docx/.pdf(or client format converted outside the workspace), indeliverables/reports/.
Output Format
- Writing Spec (
memory/<engagement>-writing-spec-<date>.md) — TOC + per-section table/chart flags + page budget + placeholder-slot list - Full deliverable draft (Markdown, chapter order matching the Writing Spec exactly)
- Chapter-by-chapter page count vs. target
- Final deliverable as
.docx/.pdf(or the Markdown draft for conversion to the client's required format outside the workspace), validated memory/YYYY-MM-DD.mdengagement summary entry
Related Skills
consulting-report-writing— prerequisite; general report-writing standardsk-dart,financial-statement-analysis— financial research inputs (with DART-fallback procedure)k-law— legal / regulatory research inputcompany-intelligence,competitive-intelligence— company / industry research inputsinsight-synthesis— cross-source synthesis for narrative chapters
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.