---
name: artifact-guidelines
description: Guidelines for writing reports, organizing files, and generating code artifacts
---

# 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?