# Issue tracker: Local Markdown with Gitea as a companion

The local issue tracker is the source of truth for this repository. Store issues and specifications as Markdown files under `.scratch/`.

## Local conventions

- Use one directory per feature or effort: `.scratch/<feature-slug>/`.
- Store its specification at `.scratch/<feature-slug>/spec.md`.
- Store implementation issues in `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`, one issue per file.
- Record triage state in a `Status:` line near the top of each issue file; use the mappings in `docs/agents/triage-labels.md`.
- Append comments and conversation history under a `## Comments` heading.

## Gitea Issues

Gitea Issues may also be used as a companion tracker. The repository remote supplied by the user is `ssh://git@git.my-rm.com:2222/Robot-Market/mqtt-5-learning.git`. There is no automatic synchronization: when an issue is represented in both places, keep the local Markdown file authoritative and include the corresponding Gitea issue link there. Do not assume a Gitea CLI or API workflow is configured.

## Skill operations

- When a skill says to publish an issue or specification, create the local Markdown file under `.scratch/<feature-slug>/`.
- When a skill says to fetch a ticket, read the referenced local file; the user may provide its path or issue number.
- For wayfinding, store the map at `.scratch/<effort>/map.md` and child tickets under `.scratch/<effort>/issues/`. Child tickets use `Type:` (`research`, `prototype`, `grilling`, or `task`), `Status:` (`claimed` or `resolved`), and an optional `Blocked by:` list. Claim by setting `Status: claimed`; resolve by adding an `## Answer`, setting `Status: resolved`, and adding a context pointer to the map's Decisions-so-far.