Work Tracker

---
name: work-tracker
description: Reads, files, claims and closes records in the ledger tracker. Use to plan work, check what is ready, file a bug, or claim an issue before work starts.
---
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# Work Tracker

The tracker is an append-only event log in `.basicly/ledger/`, committed with the code.
A record is the fold of its events. The engine reads and writes the log directly.

## Rules

- **Prefer the installed engine for writes when `basicly` is on PATH.** Use `basicly tracker write --` before `create`, `update`, `review`, `confirm`, `close` or `comments add`; claim with `update <id> --status in_progress`. These narrow command rules survive Claude auto mode. The Python commands below remain available to standalone consumers, with their normal permission checks.

- **Name a record by its title, with the id as the address.** A person cannot read a bare id.
- **File or find the record before you do the work.** The `tracker-commit-msg` hook refuses
  a commit that names an id the ledger does not hold.
- **Run `create` alone, then read the id from its reply.** The id is random, so a commit
  chained after it with a guessed id is refused.
- **Many people share this tracker. Never take a story that someone holds.** `ready` names
  the holder of each reserved story, and the supervisor skips stories that another person
  holds. `--take` is for an agreed handover only.
- **Reserve a story before you plan it, and push at once.** Others see a reservation only
  after they pull:

  ```sh
  python3 .basicly/core/kit/tracker/cli.py assign .basicly/ledger <id>    # reserve it for you
  python3 .basicly/core/kit/tracker/cli.py claim .basicly/ledger <id>     # reserve it and start
  python3 .basicly/core/kit/tracker/cli.py unassign .basicly/ledger <id>  # give it back
  python3 .basicly/core/kit/tracker/cli.py ready .basicly/ledger --mine   # what you hold
  ```

  The holder name is `git config user.name`, or `--to`. `basicly loop` records the person
  who runs it as the holder, and it stops on a story that someone else holds.
- **Never edit, delete or reorder a line in an event file.** Every derived answer changes
  and nothing detects it. Append the write that supersedes the wrong one.
- **Count from the file, interpret through the engine.** Grants, gate results and phases
  derive from ordered events under rules that a regex cannot see.
- **Probe against a scratch ledger directory, never the live one.** The log has no undo,
  and the loop commits every probe event into project history.
- **Check the output shape before you parse it.** `show` on an absent record prints
  `{"found": false}`. `create` prints `created: <id>` unless the argv carries `--json`.
- **Use one ledger per repository, never one per worktree.** The git-ignored
  `.basicly/ledger/redirect` points every worktree at the same log. A per-worktree ledger
  loses the writes of a lane at teardown.

**Stage the claim with its code.** Commit hooks read the Git index. In a shared-ledger
worktree, publish the claim on the base and update the lane from that committed base
before committing its code.

## Read when needed

- For selective reads, standalone kit commands, historical state or the served page, read [read](references/read.md). Start with a summary or the existing record and latest handover; use a session summary only when useful.
- Before a write, review or close, read [write](references/write.md) for the exact grammar, Context/Acceptance/optional Requirements and evidence contracts. Existing approved scope needs no new refinement conversation.
- For imports, shard folding or bulk ledger queries, read [maintenance](references/maintenance.md).
- Completion means the actual change and evidence are recorded with attribution and shared history preserved; close only after the whole task is satisfied.