experiment-log-to-report

name	experiment-log-to-report
description	Parse university lab requirements, report templates, and incremental experiment evidence into a persistent experiment log, local image-path plan, missing-material checklist, and a final authentic Markdown report. Use when the user is doing a course experiment over multiple turns and wants staged recording before final report generation.

Experiment Log To Report

Overview

This skill supports a multi-turn university lab workflow:

1. Parse experiment requirements and report templates.
2. Build a structured experiment log instead of drafting the final report too early.
3. Keep local image paths and captions consistent.
4. Generate a Markdown report only after the user explicitly says the experiment is finished.

The default output is:

• Structured experiment records
• Image path index
• Markdown report
• Missing-material checklist
• Pending-confirmation checklist

Do not generate docx. Do not claim results the user did not provide.

When To Use

Use this skill when the user is:

• Uploading lab manuals, PPTs, templates, sample reports, or submission rules
• Sending screenshots, command output, code snippets, tables, or spoken descriptions during an experiment
• Asking to maintain experiment progress across turns
• Asking for a final Markdown experiment report based on prior records

At the start of a new experiment workflow, remind the user that screenshots must expose a local file path if they need to appear as real Markdown images in the final report. A screenshot pasted only into chat can be analyzed and recorded, but it cannot be copied into images/ unless the environment provides a file path or the user later supplies the original image path.

Do not use this skill for one-shot fake report generation or for filling data that the user never supplied.

Working State

Keep the working files in the current task workspace unless the user specifies another location.

When the workspace is also a Git repository for publishing this skill, keep repository hygiene strict:

• Track only the skill files and public documentation by default.
• Keep user experiment state, screenshots, rendered pages, source submissions, final reports, and planning logs out of Git unless the user explicitly asks to publish a sanitized example.
• Store real experiment materials under ignored folders such as experiment_state/.
• Do not place personal experiment files in the repository root.
• Before git add, check git status --short --ignored and only stage skill-related files.

Use one independent folder per experiment. Do not mix multiple experiments in the same state directory. Recommended layout:

• ./experiment_state/exp2/
• ./experiment_state/exp2/images/
• ./experiment_state/exp2/pages/
• ./experiment_state/exp3/
• ./experiment_state/exp3/images/
• ./experiment_state/exp3/pages/

Recommended state files inside each experiment folder:

• requirements_summary.json or requirements_summary.md
• report_template.json if the template is experiment-specific
• experiment_records.json
• experiment_record_table.md
• image_index.json
• final_report.md
• report_validation.json

User images should stay outside the skill folder and inside the current experiment's images/ directory. Reference them with Markdown paths that are relative to the final report file, not relative to the workspace root. If the report is ./experiment_state/exp3/final_report.md, use ./images/exp3_step_001_hbase_install_version.png.

Do not ask the user to confirm routine screenshot filenames. Assign a stable path yourself, copy or move the image into the current experiment's images/ directory when an original file path is available, and record the assigned path directly. If the chat image is visible but no local source path is exposed, still assign the intended ./images/... path and treat it as a file-availability gap, not as a user-confirmation question.

When switching experiments, first create or select the experiment folder, then write all new records, rendered PDF pages, images, reports, and validation outputs under that folder.

Workflow

Phase 1: Parse Materials

When the user provides a lab manual, PPT, template, sample report, or submission rules:

1. Read the materials directly if Codex can inspect them.
2. If structured extraction will help, run:
   • scripts/extract_requirements.py
   • scripts/parse_report_template.py
3. Output all of the following:
   • Experiment requirement summary
   • Scoring checklist
   • Recommended report structure
   • Materials that must be collected during the experiment
   • Missing or unclear source materials

Read references/report-section-rules.md when mapping template headings to report sections.

Phase 2: Record Experiment Steps

When the user sends new experiment evidence, do not generate the full report yet. Create or update one structured record.

Each record should contain:

• Step ID
• Step title
• Related requirement
• Material type
• User input summary
• Commands
• Input materials
• Output results
• Image paths
• Status
• Problems
• Solutions
• Analysis text that can be reused in the report
• Missing information
• Confirmation state for interpretation or unclear evidence, not for routine image filenames

Use scripts/organize_images.py to suggest consistent local image paths and captions. Use scripts/add_experiment_record.py to save the record.

Read references/experiment-log-schema.md before changing the record schema.

For each newly recorded step, respond in this structure:

## 已记录实验步骤

步骤编号：step_001
步骤名称：环境配置与服务器连接
材料类型：终端截图
建议图片路径：./images/step_001_ssh_login.png
建议图注：图 1：SSH 成功连接实验服务器
报告位置：七、实验步骤及操作 → 7.1 环境准备

### 可写入报告的文字

...

### 待确认内容

- ...

Phase 3: Maintain The Master Log

Maintain an experiment master table throughout the task. The table should summarize step ID, step title, material type, image path, status, confirmation state, and notes. Do not add notes such as “please confirm the screenshot path”; only list missing source files when the image file is not actually available on disk.

Use scripts/add_experiment_record.py to update:

• experiment_records.json
• experiment_record_table.md

After each new material arrives, state:

• Identified experiment step
• Suggested image path
• Suggested caption
• Report section placement
• Reusable analysis paragraph
• Current missing materials
• Whether the user should confirm the interpretation, only when the content is ambiguous or affects report correctness

Phase 4: Generate The Final Report

Only generate the final Markdown report when the user explicitly says one of the following or equivalent:

• “实验结束”
• “生成最终报告”
• “整理成 Markdown”
• “可以写报告了”
• “根据前面的内容生成报告”

Before writing or overwriting a complete final report, first provide a concise pre-generation checklist and wait for user confirmation unless the user has already explicitly said to proceed despite missing materials in the same turn. The checklist must include:

• Missing required experiment evidence
• Optional materials that are useful but not required
• Unconfirmed or ambiguous facts
• Images visible in chat but not available as local files
• Whether the report will use placeholders for any missing items

If the user confirms generation, generate the report. If the user supplies more materials, record them first and then repeat the checklist only if meaningful gaps remain.

Run scripts/generate_markdown_report.py to build the report and scripts/validate_report.py to check completeness and authenticity constraints.

Before delivery, verify every Markdown image link resolves from the directory containing the report file. Do not assume ./images/... is correct when the report is saved in a subdirectory such as experiment_state/.

The final response should include:

• Full Markdown report body
• Image path list
• Missing-material list
• Pending-confirmation list
• Report self-check list

Read references/markdown-report-style.md before polishing the final report language.

Authenticity Rules

Read references/authenticity-rules.md whenever:

• Results are incomplete
• A screenshot is unclear
• The user only described part of a step
• Performance metrics or summary claims are requested

Non-negotiable rules:

• Never fabricate results, screenshots, code coverage, or completion state.
• If evidence is missing, write 【待补充...】.
• If evidence is unclear, write 【待确认】.
• If a step is unfinished, do not write “成功完成”.
• Performance analysis must be based on user-provided data only.

Script Guide

scripts/extract_requirements.py

Use to consolidate requirement materials into requirements_summary.json.

Example:

python .\scripts\extract_requirements.py .\materials\guide.docx .\materials\submit_rules.txt --output .\experiment_state\requirements_summary.json

scripts/parse_report_template.py

Use to extract report headings and placeholders from templates or sample reports.

scripts/organize_images.py

Use to suggest or register image paths under ./images/.

scripts/add_experiment_record.py

Use to create or update one experiment record and regenerate the master table.

scripts/generate_markdown_report.py

Use after the user confirms the experiment is finished.

scripts/validate_report.py

Use before delivering the final report. Treat warnings and missing evidence explicitly instead of hiding them.

Reference Navigation

• Section placement rules: references/report-section-rules.md
• Log schema: references/experiment-log-schema.md
• Markdown writing style: references/markdown-report-style.md
• Authenticity guardrails: references/authenticity-rules.md

Decision Rules

• Prefer updating existing records over creating duplicate steps.
• Prefer concrete file paths over vague references like “later add screenshot”.
• Prefer placeholders over invented content.
• Prefer stating uncertainty clearly over smoothing the text.

If the user later asks for Word output, keep this skill focused on Markdown content and tell them the Markdown can be imported or converted separately.