mqtt-5-learning/docs/agents/issue-tracker.md

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.