by bonsai_spool | 2026-01-04 10:25:00+00:00
No problem! I recommend asking Claude for these sorts of things so they can better match your own processes.

----

New session:

## Prompt

Set up project documentation structure for this new project.

Create the following:

1. \*CLAUDE.md\* (project root) - Concise (<40 lines) entry point with:
- One-line hypothesis/goal
- "Start Here" pointing to docs/ROADMAP.md
- Quick Reference (key commands)
- Key Files table
- Documentation links
- "End of Session" protocol (append to docs/session_log.md)

2. \*docs/ROADMAP.md\* - Status dashboard:
- Current state table (what exists)
- Blockers table (with links to plans)
- Priority actions table (with links to plans)
- Success criteria (minimum + publishable)

3. \*docs/plans/\* directory with plan templates:
- Each plan: Priority, Status, Depends on, Problem, Goal, Steps, Success Criteria
- Name format: plan_descriptive_name.md (not numbered)

4. \*docs/runbook.md\* - Common operations:
- How to add new data sources
- How to run analysis
- How to run tests

5. \*docs/session_log.md\* - Work history:
- Template for session entries
- "Prior Sessions" section for context

6. \*docs/archive/\* - For completed/old docs

If this is a data pipeline project, also set up:
- SQLAlchemy + Pydantic architecture (see sqlalchemy_pydantic_template.zip)
- tests/ directory with pytest structure
- you can copy the file from ./generic_claude_project_src.zip to the current folder and unzip the copy. DO NOT modify the original file or try to move the original file

Keep all docs concise. Link between docs rather than duplicating.

---

## After Setup Checklist

- [ ] CLAUDE.md is <50 lines
- [ ] ROADMAP.md fits on one screen
- [ ] Each plan has clear success criteria
- [ ] runbook.md has actual commands (not placeholders)
- [ ] session_log.md has first entry from setup session

---

## python

use the py-PROJECT pyenv

ensure pyenv is installed

## Example Structure

project/
├── CLAUDE.md # Entry point (<50 lines)
├── docs/
│ ├── ROADMAP.md # Status + plan links
│ ├── runbook.md # Common operations
│ ├── session_log.md # Work history
│ ├── plans/
│ │ ├── plan_data_loading.md
│ │ ├── plan_analysis.md
│ │ └── plan_validation.md
│ └── archive/
│ └── plans/ # Old plans with date prefix
├── src/ or project_name_src/ # Code
└── tests/
└── test_*.py

## Session log example

## YYYY-MM-DD: Brief Title
\*Goal\*: What you aimed to do

**Done**: What was accomplished (be specific)

**Discovered**: Non-obvious findings about codebase/data/tools

**Decisions**: Choices made and brief rationale

**Deferred**: Work skipped and why (not just "next steps")

**Blockers**: Issues preventing progress (or "None")

The key shift: less about tasks completed, more about knowledge gained that isn't captured elsewhere.

Continuation prompt

Review the project state and tell me what to work on:
1. Read docs/ROADMAP.md
2. Read docs/session_log.md (last entry)
3. Read the highest-priority plan in docs/plans/

Then summarize:
- Last session (1 line)
- Current blockers
- Recommended next step

Ask if I'm ready to proceed.

1. pyenv activation syntax varies by shell
## Python
Use py-dissertation pyenv. Activation:
{bash
# If using pyenv-virtualenv
pyenv activate py-dissertation
# Or set for directory
pyenv local py-dissertation}

**2. No requirements.txt created**
{markdown
If using SQLAlchemy template, create requirements.txt:
- sqlalchemy>=2.0
- pydantic-settings
- pytest
- pytest-cov}

3. Template contents unknown upfront
The generic_claude_project_src.zip contains:
- src/config.py (pydantic-settings)
- src/database.py (SQLAlchemy session management)
- src/models/base.py (Base, ProvenanceMixin)
- src/loaders/base_loader.py
- Empty src/dtos/, src/models/, src/loaders/ packages

4. Missing project context
Before creating docs, briefly describe:
- Project hypothesis/goal (1 sentence)
- Data sources (what files exist, what format)
- Expected outputs (tables, figures, etc.)

5. data/ directory not in template
Also create: data/ directory (for database.db, cache/)

6. Ambiguity on "actual commands" in runbook
- runbook.md: For operations not yet implemented, use format:
`# TODO: Add when [plan_name.md] is complete`
rather than placeholder commands

7. Git initialization missing
Initialize git:
{bash
git init
echo "data/\n*.db\n__pycache__/\n.pytest_cache/" > .gitignore}

**8. First session log entry guidance**
{markdown
session_log.md first entry should list:
- What was created (not just "project structure")
- Key decisions made (e.g., "SQLAlchemy for ORM")
- What to review first (e.g., existing data files)
}

The zip archive above is just a standard Python module with __init__ and hints at how I'd like things to be named.*