# Task folder improvements

## Current pattern
Current task folders are useful but inconsistent.

Observed states:
- some tasks only have `README.md`
- some task folders are basically artifact dumps
- some advanced folders already invented good structure:
  - `STATE.md`
  - `TASKS.md`
  - `UPDATES.md`
  - prompts/scripts/artifacts together

So the issue is not missing capability.
The issue is missing a lightweight standard.

## Goal
Make task folders cheaper to resume, validate, and hand off without turning them into bureaucracy.

## Recommended standard

### Minimum for every real `T-xxx/`
- `README.md`
- `STATE.md`
- `artifacts/` directory when files/outputs exist

### Optional files when useful
- `EVIDENCE.md`
- `DECISIONS.md`
- `TASKS.md` for repo-local substeps
- `UPDATES.md` for dated progress log
- `scratch/` for disposable drafts/greps/tmp notes

## What each file should mean

### `README.md`
Stable identity.
Keep short.

Suggested fields:
- Goal
- Source
- Scope / exclusions
- Main repo(s) / path(s)

Do not turn this into a running log.

### `STATE.md`
This is the highest-value addition.
One file that answers:
- current status
- next step
- blockers
- done gate
- latest reality/truth status
- where evidence lives

Suggested shape:
- Status: queued | active | blocked | done
- Objective:
- Done gate:
- Not doing:
- Reality constraints:
- Current state:
- Next step:
- Blockers:
- Evidence:
- Last updated:

If only one file beyond README exists, this should be it.

### `artifacts/`
Put generated outputs, screenshots, exported logs, sample data, prompt files, HTML captures, PDFs, etc.

Rule:
- user-facing or validation-relevant files -> `artifacts/`
- not mixed loose at task root unless they are primary docs

Suggested subfolders only when needed:
- `artifacts/output/`
- `artifacts/evidence/`
- `artifacts/input/`

Do not over-nest by default.

### `EVIDENCE.md`
Use when proof matters.
Especially for:
- validation claims
- screenshots
- test output references
- links to generated files
- manual verification notes

Keep evidence pointers here instead of hiding them across chat history.

### `DECISIONS.md`
Use when the task has meaningful branch choices.
Short entries:
- date
- decision
- why
- rejected alternative if useful

### `TASKS.md`
Use only when the task has enough internal complexity to need local substeps.
This prevents bloating the global task list.

### `UPDATES.md`
Use for chronological progress only when the task spans many passes or multiple agents.
Not mandatory.

### `scratch/`
Use for low-value intermediate material.
Can be cleaned aggressively.

## Root hygiene rules
Inside each task folder:
- docs at root
- durable outputs in `artifacts/`
- temporary clutter in `scratch/`
- scripts only if task-specific and worth keeping

Avoid giant flat roots full of mixed png/txt/md/sh files unless the task is truly one-off.

## Naming rules
Prefer stable generic names over date-stamped chaos.

Good:
- `STATE.md`
- `EVIDENCE.md`
- `artifacts/preview.png`
- `artifacts/test-output.txt`

Less good:
- `notes2-final-v3.txt`
- `tmp2.png`
- `really-final-output.pdf`

Dates belong inside content or when multiple snapshots genuinely matter.

## Two-tier standard

### Tier 1: default
For most tasks:
- `README.md`
- `STATE.md`
- `artifacts/` if needed

### Tier 2: heavier tasks
Add only when justified:
- `EVIDENCE.md`
- `DECISIONS.md`
- `TASKS.md`
- `UPDATES.md`
- `scratch/`

## Best next repo change
Update `docs/task-system.md` with:
- minimum folder template
- meaning of `STATE.md`
- root hygiene rules

Then optionally add a helper like:
- `bin/task-init T-123 --goal "..." --source "..."`

That helper should create:
- `README.md`
- `STATE.md`
- `artifacts/`
- `scratch/`

## Recommendation
Adopt this small standard:
1. require `README.md`
2. require `STATE.md`
3. use `artifacts/` for durable outputs
4. add other files only when complexity demands them

That gives most of the value without making every task folder heavy.