MISCROSPEC.md

Method: micro spec agentic flow

We follow a micro spec approach where each development task is described as a short markdown card annotated with data in YAML front matter.

Workflow rules

• ALWAYS work one card at a time.
• ALWAYS finish the ongoing card(s) before working on another one.
• If you plan something, write your plan to the card and mark it analyzed.
• If you move a card from todo to ongoing, make sure to include your plan and to-do list within the card.
• If you finish implementing something, write a summary of changes to the card and mark it done.
• If you've been prompted to work on something without having a todo or ongoing card, create a new card before starting the work.
• A card MUST exist and be included in every commit. Never commit without the corresponding card file.
• Every time you reach a milestone, commit everything, including changes to the task file(s).
• Every time you commit, run the tests first, they must pass.

Summary of state transitions

Only the following transitions are allowed:

todo -> ongoing        # when you start working
ongoing -> analyzed    # when you've written a plan that needs a human decision
ongoing -> done        # when you've finished the work

Micro spec card format

A micro spec card is ALWAYS a markdown document.

Markdown document

The format below MUST ALWAYS be used.

# What we are working on in one sentence (card title)

A quick summary of the idea, in up to one paragraph (card summary). This should
be end-user oriented, whoever the end-user is. Typically the problem to solve.

## Subsections (card description)

Then come various sections with more details. Typical examples are

* `## Idea` that describes the idea to solve the problem
* `## Todo` with a markdown checkbox-list of things to work on
* `## Plan` with the details of an analysis
* `## Changes` with what has been done

The document maps the "say it in one sentence, one paragraph, one document" way of managing information in Klaro Cards.

Example

# Add CSV export to the reports feature

Users need to export their reports to CSV format for use in spreadsheets
and external tools. Currently only PDF export is available.

## Idea

Add a new "Export CSV" button next to the existing PDF export. The CSV
should include all visible columns with proper escaping.

## Todo

- [x] Add CSV export function to report utils
- [x] Add export button to report toolbar
- [x] Write unit tests for CSV generation
- [ ] Update documentation

## Changes

- Added `exportToCsv()` in `src/utils/export.ts`
- Added CSV button in `src/components/ReportToolbar.tsx`
- Added tests in `tests/export.test.ts`