yapi777/create-doc

Create-doc — Create an Outline for the Slide-Building Skill

Read research records (execution logs .md, result CSVs, figures, code) and write a slide-by-slide outline in Markdown that defines for each slide: "what to say, which layout type to use, what content to include, and what the speaker notes are".

The output is consumed by the progress-report-deck skill (located in the same research-slides plugin, in the folder ${CLAUDE_SKILL_DIR}/../progress-report-deck/). This skill's output is built on the premise that progress-report-deck will parse each ## heading as one slide and inject the content into a template. Before starting, read ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md and verify the rules below ("Conventions with the Slide-Building Skill") are consistent (if the other skill's rules have changed, adapt to them). If not found, follow these conventions.

If the user's profile ~/.claude/yapi-skills/profile.md (name, research field, main audience, custom rules) exists, read it first. Custom rules (e.g., color scheme, minimum font size) take precedence over the conventions below and must be copied into the "About This Document" section of the outline.

A sample outline is available at references/template.md. If in doubt about formatting, match that template.

Conventions with the Slide-Building Skill (derived from progress-report-deck rules)

The outline must follow these rules. Failure to do so will result in slides being trimmed or reworked during the slide-building phase.

Item	Convention	Reason (progress-report-deck rule)
Headings	Each ## = one slide. Use ## only for slides, including backup slides. Use # for section headings (e.g., chapter divisions)	The outline's ## are read as slides
Skeleton	Title → What Was Done This Time (Table of Contents) → Research Background (1/2)(2/2) → Research Objective (This Time's Sub-goal) → Content → Summary & Future Work → Thank You	Fixed template skeleton
Research Background	If unchanged from last time, just write "Carried over (as in base material)" without repeating content	Research background is typically carried over
This Time's Sub-goal	Must include the phrase "This Time's Sub-goal" on the Research Objective slide (1-2 lines)	The other skill asks the user for this every time; decide in advance
Slide Count	Write the final slide count (avoid requiring merging or splitting later)	The other skill suggests merging if too many ##
Layout Type	Each content slide must specify one layout type (see table below)	If only bullet points are provided, the other skill will flag "lower half is blank"
Color Scheme	Only two colors: Blue = proposal, response, conclusion, key numbers; Orange = existing method, problem, criticism, caution. Do not assign a third color per method. In tables, highlight the key row as "emphasized in light blue"	Theme uses only blue #156082 and orange #E97132
Text Length	Each claim must be within 30 full-width characters (fits in one line at 18pt full width). Each bullet point item also within ~30 characters. Max 3 lines per panel. If longer, use a figure/table or split the slide	Minimum font size is 16pt, cannot be shrunk to fit
Font Size	Do not write instructions like "smaller font" or "use smaller text for footnotes". Footnotes must also fit in one line at 16pt	Fonts below 16pt are forbidden
Formulas	Write using $...$ (LaTeX notation) and explicitly state "Formula (OMML)"	Formulas are rendered using OMML
Figures	Specify PNGs copied to the output folder's images/ as images/<name>.png (if only PDF available, convert to PNG and place there). Do not use repository paths or ../. Also consider whether the figure fits within a 4:3 slide (e.g., place two landscape figures vertically)	PNGs are embedded in PPTX. Slides are 4:3. Slides may be built on a different folder or machine; paths outside the folder are inaccessible
Schematic Figures	For content that needs a diagram but has no file (e.g., process flow, timeline, before/after comparison), specifically describe the layout type and how to draw it	The other skill can handle diagram creation without asking the user
Speaker Notes	Write speaking content in the "Notes" section. Do not include it on the slide	—
Backup Slides	Place Q&A backup slides after the "Thank You" slide	The closing is the end of the main content

Available Layout Types (see examples in progress-report-deck's assets/template.pptx):

Type	When to Use	Example from template.pptx
Chip + Panel (Problem → Response)	"Existing problem → Current response", "Criticism → Response"	p.7, p.11
Numbered Badge + Panel	Enumeration of numbered items (①②③) e.g., advantages, steps	p.8-9
Before/After Schematic	Comparison of existing vs. proposed method (left = orange frame, right = blue frame, arrow in between)	p.10
Timeline Schematic	Time-direction process flow (solid/dashed boxes + connectors)	p.12
2-Column Chip + Panel + Bottom Bar	Side-by-side comparison of two methods/settings, with formulas	p.13
Table + Full-Width Bar	Result table with a bar below highlighting the key takeaway (one row in dark blue)	p.14
KPI Tiles (2×2)	Highlight four key numbers or conclusions in large text	p.15
Checklist (✓)	List of confirmed items or tasks completed	p.16
Framed Box 2-Stack	Summary / Future prospects	p.17
Figure + Full-Width Bar	Embed an existing figure large, with a bar below for the takeaway	(p.14 table replaced by figure)

The Table of Contents slide (What Was Done This Time) does not have a layout type (just a bullet list with key terms bolded; no colors).

Procedure

1. Gather Requirements (AskUserQuestion, in a single query)

Do not ask about things already clear from the conversation or request. Only ask what is unclear.

• Presentation type and duration: Progress report / Seminar / Conference. Rule of thumb: ~1 minute per content slide (for a 15-min talk, ~10 content slides + 5-6 skeleton slides)
• Audience: Lab members / Conference / Non-specialists. This affects assumed knowledge
• Additional context to include (multi-select): Motivation/Rationale, Comparison experiments, Failure analysis, Method evolution, Bug impact, etc. Suggest topics found in the records
• Whether to keep research background as-is: If changing from last time, specify what to change

If the user provides free-text answers outside the options, treat them as requirements (e.g., "Also include X in the motivation").

2. Collect Materials (read-only; do not re-run experiments)

• Slide-building skill: ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md (to confirm the conventions above)
• Records: runlog_*.md, *results*.md, README.md, plan docs, etc. Start with the newest files
• Numerical data: summary/*.csv, tables in *.md. Always transcribe numbers for the presentation from these sources
• Figures: Search for existing PNGs using ls. Prefer figures with Japanese labels. Keep track of the original paths for copied figures (will be needed in step 4 for copying to images/ and for citing sources)
• Configuration values: Hyperparameters, constants, model architecture for backup slides should come from actual code (constants, argparse defaults, saved config JSONs), not from log notes. If there's a discrepancy between logs and code, treat the code as correct and inform the user

3. Decide on Structure

Use the skeleton (matching progress-report-deck's template):

1. Title slide
2. What Was Done This Time (Table of Contents: list content slide headings briefly)
3. Research Background (1/2)
4. Research Background (2/2)
5. Research Objective (purpose + this time's sub-goal)
6. ~ Content slides
7. Summary & Future Work
8. Thank You
9. Backup Slides (Q&A)

Content slides generally follow this flow (adjust based on slide count):

1. Motivation/Challenge (why did you do this) → Chip + Panel
2. Proposed/Changed content and advantages → Before/After Schematic or Numbered Badge + Panel
3. Method details (process flow) → Timeline Schematic
4. Correctness validation/verification → Checklist
5. Parameter determination → KPI Tiles or Table + Bar
6. Experiment setup (data, baseline methods, evaluation metrics) → 2-Column or Table + Bar
7. Results (one slide per main claim) → Table + Bar, Figure + Bar
8. Cost/Limitations → Table + Bar or KPI Tiles

Always include backup slides (Q&A). These are not counted in the presentation time.

• Detailed settings (model, optimizer, constant tables)
• Data/simulation configuration
• Baseline method details (formulas with OMML specification)
• Exact definitions of evaluation metrics
• Full results tables (e.g., parameter search)
• Anticipated Q&A with sample answers (around 8): This section is not made into slides (place it at the end of the outline as a # chapter, for the speaker's reference). Prioritize questions targeting weaknesses: "Isn't the difference small?", "Can you conclude from a single trial?", "Why this baseline?", "What is the computational cost?", "What is the basis for unverified claims?", etc.

4. Write and Package (output to a single folder)

Slides may be built by progress-report-deck on a different folder or a different machine (e.g., a PC with PowerPoint). Therefore, package the outline and all used images into one single folder so that slides can be generated from just that folder.

SlideOutline-<date>/
├── SlideOutline-<date>.md   ← the outline
└── images/
    ├── speed_sweep.png
    └── ...

• Folder name and markdown file name must both be SlideOutline-<date> (e.g., SlideOutline-2026-10-15/). Date is the creation date in YYYY-MM-DD. If the name conflicts (e.g., another presentation on the same day), append a short identifier (e.g., SlideOutline-2026-10-15-seminar/). Do not overwrite existing folders. Place the folder at the project root.
• Images: Copy all figures used in the outline to images/ (copy, not move; do not touch the original files)
  • Keep the original file name. If names conflict or the original name is uninformative (e.g., fig1.png), rename to a descriptive alphanumeric name (e.g., velocity_field_f195.png). Avoid spaces.
  • For figures that are only available as PDF, convert to PNG and place there (e.g., pdftoppm -png -r 200 -singlefile in.pdf images/name, or use PyMuPDF at 200 dpi)
  • Reference images in the outline as images/<name>.png
  • Record original paths in the "Sources" section as "images/xxx.png ← original path" (for traceability when re-creating figures)
• Schematic figures (no image file): Do not create an image; just describe how to draw them in the outline

At the top of the outline, include an "About This Document" section (a # chapter, not a slide) with instructions for progress-report-deck:

• Presentation type, duration, slide count, audience
• Format of each slide (see below)
• Do not modify or round numbers
• Set this folder as the working folder and execute progress-report-deck. Figures are in this folder's images/ and are referenced as images/<name>.png. Do not create new figures (except drawing schematics as specified)
• Naming conventions for methods, color assignments (blue = proposed, orange = existing/baseline)
• Whether to keep research background as-is

Format for each slide:

## Slide N — <Title>

- **Layout**: <one layout type from the table above>
- **Claim**: <one sentence within 30 full-width characters. The single most important thing to say on this slide>
- **Body**: <bullet points. ~30 characters per item, up to 3-4 items>
- **Table** / **Figure**: <Table in Markdown, noting rows/columns to emphasize. Figure: `relative_path.png` with a brief description>
- **Formula (OMML)**: <if any, in $...$>
- **Notes**: <speaking content. Not on the slide>

Writing rules:

• Claims must be conclusions, not topics. Write "Speed gap widens as velocity increases", not "Result 1" or "About X" or "Showing X". Use plain style, not polite "~ます/~です".
• Support evaluative words with numbers. If you write "significantly", "effective", or "superior", put the comparison object, metric, and number of trials on the same slide. Avoid overstatement like "equivalent" or "guaranteed" (use "nearly equivalent" or "confirmed").
• Do not use common AI-generated filler words (e.g., very, groundbreaking, enables [one] to, seamless). See ${CLAUDE_SKILL_DIR}/../progress-report-deck/references/ai-smell-lexicon.md for a list and replacements.
• Each bullet point should be one sentence (split if it contains two clauses connected by "and" or similar conjunctions).
• Mark unverified claims as unverified. Do not mix expected properties with experimentally shown facts. Add one line in the body or bar of the relevant slide, and also include it in the "Future Work" section of Summary.
• Conditions for fair comparison (e.g., convergence settings used) should be a one-line footnote. Long explanations about history are only included if the user explicitly requested them.
• Move detailed explanations that won't fit on a slide into Notes or backup slides. Keep body text concise.
• At the end, add a "Sources" table (content → file) as a # chapter.

5. Validate (mandatory)

1. Numerical cross-check: Use a regex to extract all decimals from the outline and verify each appears in the source .md/CSV (CSV values are rounded to 4 or 2 decimal places). For any unmatched number, check manually whether it's a self-calculated difference, a transcription error, or an inconsistent rounding, and fix. Place the validation script in the scratchpad.
2. Folder self-containment: Verify all figure references in the outline point to images/ subfolder PNGs, and that those files actually exist. Ensure no ../ or absolute paths or internal repository paths remain. Also ensure images/ contains no unreferenced files. Report total folder size.
3. Figure content inspection: For any text that describes a figure (e.g., "largest in X"), actually open the figure and verify the description matches.
4. Rule compliance check: Verify number of ## headings matches expected slide count; every content slide has a "Layout" field (except skeleton slides); no third color scheme instruction; claim length ≤ 30 full-width chars; claims are conclusions; no AI-smell words; consistent notation. Use the slide-building skill's validation script:

   python "${CLAUDE_SKILL_DIR}/../progress-report-deck/scripts/check_deck.py" --text "<outline.md>" > check_doc.txt
   

   Read the output with Read and fix any WARNs (may keep if scientifically correct). If the last line is not DONE: …, the check failed (do not assume zero issues). If the script is not found, perform this check manually.
5. Slide count: Verify the main content fits within the requested slide count.

6. Report

• Line 1: Intended audience (e.g., "Audience: progress-report-deck skill (ultimately, lab seminar attendees)")
• Output folder path and its contents (1 markdown file + number of images + total size)
• Structure (one line per slide) and backup slides content
• Validation results (number of numbers cross-checked, figure verification, rule checks)
• Points the user should know before the presentation: unverified claims, numbers likely to be challenged and why, which date/code the results come from
• Next step: Inform the user that they can run progress-report-deck on this folder (or copy the whole folder to another machine) to generate slides. Let the user decide how to transfer the folder (USB, Box/OneDrive, zip, etc.)
• Do not commit (unless asked)

---

(Note: The content from the original Skill Section "進め方" has been procedurally localized; the structure and intent remain identical.)