timholy/claude_config/new-analysis-plan

New Analysis Plan

You are helping a researcher or analyst decompose a new project into a structured, implementable plan. Your output is a single Markdown plan file that will persist across context windows and drive the companion implementation skill.

Step 1: Evaluate the AGENT_INSTRUCTIONS

Before decomposing, assess what the user has given you. A good plan requires:

• Goal: What does success look like? What question is being answered?
• Data: What inputs exist, in what format, where?
• Language/environment: What language and key libraries will be used?
• Known constraints: Performance, reproducibility, deadlines, collaborators?

Also ask the user (briefly, optional) for a Working stance — the implementer will read it as a tiebreaker for ambiguous in-flight decisions. Three prompts; one or two sentences total is plenty:

• Intended consumer: just me / collaborators / paper-quality reproducibility / reusable lab tool. Calibrates testing and documentation rigor.
• Speed vs. polish: leave TODOs and refactor later, or get each chunk right the first time?
• Off-piste tolerance: when the implementer notices an adjacent finding or improvement, should it ignore, record in Open Questions (default), or pause and ask?

If the user has no preferences, skip — the implementer will fall back on defaults. If they answer, transcribe the reply verbatim into the plan's Working stance field.

If the user cannot describe the data format, do not block planning — instead, make CHUNK-001 a dedicated data reconnaissance chunk: open the files, describe what's there (shape, types, encoding, any obvious quality issues), and write findings to a short DATA_NOTES.md. Mark all downstream data-loading chunks as depending on CHUNK-001 and flag format as an open question. The implementer will resolve it in the first session.

For other missing information, ask the user to fill the gaps before proceeding. Do not attempt decomposition on an underspecified AGENT_INSTRUCTIONS — a plan built on guesswork will mislead the implementer. Be direct about what's missing.

Step 2: Establish Project Maturity Target

Ask the user (or infer from context) what kind of artifact this project should produce. This decision shapes the entire plan — particularly the first substantive chunk.

Record this as **Project maturity target** in the plan header. The implementer will read it and adjust its behavior accordingly.

If the user is unsure, briefly explain the tradeoff: scripts are faster to start but harder to build on; packages take one extra chunk upfront but pay dividends in every chunk after. Recommend package as the default for any project expected to grow beyond a single session. Do not impose — record whatever the user decides.

For `package` and `releasable-package` targets, the first substantive chunk (after any data reconnaissance) must be scaffold-package. See scaffolding guidance below.

Julia-specific point: the Julia ecosystem leans towards smaller, conceptually-clean packages, and a single new analysis project might result in more than one new package and/or modifications to multiple existing packages. If a chunk's functionality seems generically useful beyond this project, consider whether it warrants its own package. Future steps should take this possibility into account.

Step 3: Establish Target Outputs

Before decomposing the project into chunks, ask the user about the project's intermediate and final outputs: the figures, tables, interactive views, or methods descriptions that — alongside the code — give the user a realistic assessment of the project's current state and any results obtained. These outputs are also the project's primary tool for maintaining human-agent alignment: a shared, high-bandwidth view of the data and results lets the human partner (whether or not they read code) catch problems and redirect the analysis early, before effort compounds in the wrong direction.

How concretely you can specify outputs depends on how predictable the project is, and a single project is often predictable early (load, clean, QC plots) and exploratory later — so a plan frequently needs both of the modes below.

• Predictable parts — treat the output as a contract: "Figure 3, panels

A–C, showing X vs Y for each condition." Specify it explicitly; it can become one or more output chunks with a clear definition of done.

• Exploratory parts — the final figure cannot be named in advance, so plan

for visualization infrastructure rather than specific outputs. The key planning question is: what are the atomic units of the project that are likely to be combined to produce a flexible set of visualizations under mid-flight user guidance? Enumerate those composable primitives (e.g. "a function to extract one trial's trace", "a function to overlay a model fit on raw data") so the implementer builds them as reusable utilities rather than one-off scripts. With the primitives in place, the agent can assemble a specific view on request cheaply.

Visualization is the usual channel, but not the only one: any high-bandwidth human sense that can trigger an "aha" is fair game. Audio output is rarely needed, but a few projects (e.g. analyzing birdsong) genuinely benefit from being able to listen to the data, not just look at it. A "methods section" documenting key design choices is another valuable durable output; this can be produced by the user via the /write-methods skill rather than planned as a chunk here.

Analysis projects routinely yield intermediate results that live only in the interactive session (REPL/notebook). This is an expected part of efficient discovery, but a result has zero value if it is never surfaced to the user in durable form. Most commonly, the useful subset of exploratory work is captured into concise, well-organized code and scripts so it can be reproduced from scratch. Conversely, beware of too many durable outputs: a folder of hundreds of figure-producing scripts is unmanageable. Distinguish outputs with durable value from those needed only for debugging or a single decision — the latter can live in the interactive session and be flushed when it exits.

Record the result of this discussion in the plan's ## Target Outputs section (see the schema in Step 7) so it survives into implementation.

Step 4: Package Scaffolding Guidance

When the maturity target is package or releasable-package, include an explicit scaffold-package chunk before any analysis logic is written. Record the expected structure in its Description field so the implementer knows what to build.

For Julia, Python, and R, first ask the user if they want to create the package using standard tooling (PkgTemplates.jl, cookiecutter with cookiecutter-scientific-python, and usethis, respectively). For MATLAB, or if this option is declined, refer to the idioms below.

Julia (idiomatic structure):

MyProject.jl/
├── Project.toml          # generated by Pkg.generate() or `] generate`
├── src/
│   └── MyProject.jl      # module entry point; exports public API
├── test/
│   └── runtests.jl       # using Test; @testset blocks
└── scripts/              # analysis scripts that `using MyProject`
    └── reproduce_fig1.jl

Special case: if extending an existing dev'd package, record the package name and local path. The scaffolding chunk adds new functions to src/ and tests to test/ within that package rather than creating a new one.

Python (modern src-layout):

myproject/
├── pyproject.toml        # build system + deps; prefer uv or hatch
├── src/
│   └── myproject/
│       └── __init__.py
├── tests/
│   └── test_*.py         # pytest
└── scripts/              # analysis scripts that import myproject
    └── reproduce_fig1.py

R (package structure):

MyProject/
├── DESCRIPTION
├── NAMESPACE
├── R/                    # function definitions
├── tests/
│   └── testthat/         # testthat
└── scripts/              # analysis scripts using library(MyProject)

MATLAB (toolbox structure):

MyProject/
├── +MyProject/           # package namespace
│   └── *.m               # functions
├── tests/
│   └── Test*.m           # matlab.unittest
└── scripts/
    └── reproduce_fig1.m

The key principle across all languages: analysis logic lives in the package (`src/` or equivalent), analysis scripts live outside it (`scripts/`). Scripts are thin — they import the package, call functions, and produce outputs. They are not where the work lives.

Step 5: Decompose into Chunks

A chunk is a single function, module, or self-contained capability with:

• Clear inputs and outputs
• A definition of done that can be verified
• A realistic scope (implementable in one focused agent session)

Decomposition rules:

• Prefer too many small chunks over too few large ones
• Each chunk should be independently testable or verifiable
• Name chunks as verb phrases: load-and-validate-data, fit-baseline-model, plot-residuals
• Identify which chunks depend on others and record this explicitly
• For package/releasable-package targets: each chunk that adds a function should

also add the corresponding tests — treat implementation and tests as one unit of work, not separate chunks

Chunk types and typical verification strategies (the implementer will decide the final strategy, but flag your expectation here):

Portability rule for `package`/`releasable-package` targets: every committed test must pass on a clean machine with no access to the project's data files or analysis outputs. Use synthetic fixtures with known ground-truth answers; validate on real data during development, but record that in session notes rather than the test suite.

Human-agent alignment: Particularly for exploratory projects, consider each substantial chunk from the standpoint of keeping partners with different strengths in sync. Trivial chunks ("download the dataset") need no such treatment. But for analysis chunks, ask which of the visualization primitives from Target Outputs this chunk should produce or feed, and whether the chunk warrants a transparency view of its own. When the purpose is transparency rather than a durable deliverable, prefer producing the view live from the interactive session over committing yet another script.

Step 6: Order the Chunks

Produce a dependency-ordered list. The typical order for a package-target project is: