uchicago-data-analytics-analysis-state

Analysis State

Purpose

Turn a useful conversation into durable project knowledge so future Claude Code sessions can resume without rediscovering decisions.

Do not call this "memory" to users. Say "save analysis state" or "save reusable analysis notes."

When To Offer

Offer at logical checkpoints:

• after file/dataset discovery
• after business definitions are confirmed
• after a warehouse analysis brief is confirmed
• after a baseline scenario is defined
• after final results/report
• before a long next step
• before context becomes large

Use simple wording:

We’ve reached a good save point. I can save the decisions so a future session
can pick up from here. Suggested name: <analysis-name>. Should I save it?

Files To Create Or Update

Under work/<analysis-name>/, create/update only files that fit the analysis:

ANALYSIS.md      # goal, route, decisions, assumptions, latest result
DATASETS.md      # files, aliases, sheets, grains, keys, caveats
DEFINITIONS.md   # confirmed business terms, metrics, formulas
SCENARIOS.md     # baseline, parameters, scenario results
QUESTIONS.md     # open questions and next steps
outputs/         # generated extracts
reports/         # generated reports local to the analysis

Never overwrite source data. Append/update notes carefully; preserve user edits.

Optional Local Skill

When an analysis becomes repeatable, offer to create:

work/<analysis-name>/skills/<analysis-name>/SKILL.md

The local skill should instruct future sessions to load the state files first and preserve confirmed definitions unless the user changes them.

Save Content

Capture:

• original user goal
• selected route and domain/data area
• dataset aliases and paths
• confirmed grain and keys
• metrics and formulas
• filters and exclusions
• scenario parameters
• environment used for warehouse results
• assumptions and caveats
• open questions
• latest report/output paths

Do not save credentials, identifiers, or sensitive row-level examples.