Report Writing and File Organization

Report Writing and File Organization

This skill provides best practices for all subagents when generating written artifacts, code files, and figures.

Writing Guidelines

Use GitHub-flavored CommonMark markdown for all text outputs (reports, logs, documentation). Never use plain .txt files.

Write concisely:

• Short paragraphs with complete sentences
• Favor insight over exhaustiveness
• Use lists sparingly, only when they genuinely clarify (e.g., model assumptions, validation criteria)
• Avoid markdown overuse - minimal headers and bold, no excessive formatting

In reports:

• Lead with key findings or conclusions
• Support claims with evidence (plots, statistics, diagnostics)
• Reference files with clear relative paths: "As shown in figures/​washout_curves.png..." or "washout_curves.png" if in same directory
• Document what you tried, what worked, and what didn't

In logs:

• Capture decisions and reasoning, not play-by-play execution
• Record why you chose certain paths or skipped alternatives
• Note failures and how you addressed them

Use scratchpad:

• You should create local files to write a first draft, including thinking process
• Rewrite it to form final output, then delete the temporary local files you created

Code Organization

One logical unit per file:

• One model per .stan file
• One analysis per .py script
• Descriptive names: fit_hierarchical_model.py not model.py
• Self-contained scripts that run independently

Stan only: All Bayesian models must use Stan via CmdStanPy. Do not use PyMC, NumPyro, Pyro, or other PPLs.

Keep it simple:

• No deep nesting of directories unless natural grouping exists
• Clean up exploratory scripts after consolidating insights into reports
• Every file should have a clear purpose

Figure Organization

Use descriptive filenames:

• group_washout_curves.png not fig1.png
• prior_predictive_check.png not ppc.png

One figure per concept or question:

• Avoid packing too many subplots (max 2x2 for comparisons)
• Save at appropriate resolution (300 DPI for reports, 150 for exploratory)

File Minimalism

Generate fewer, better files:

• Consolidate related content - one EDA report, not 10 partial analyses
• Combine related visualizations into multi-panel figures when appropriate
• Only create files that will be read by users or subsequent agents
• Remove intermediate artifacts after they've served their purpose

Each file you create should justify its existence. Ask: will this be read? Does it convey unique information?