A loose idea emerges: it's too big to fit into a single agent session, and the path ahead is still in the fog. This skill will map it into a shared map on the repo issue tracker, then handle one ticket at a time. The Map is domain-agnostic: it works for engineering work, course content, or anything that fits this shape.
Refer by name
Each map and each ticket is an issue, so it has a
name: its title. In all human-facing content, including narratives and the map's Decisions-so-far, refer to it by name, not just by bare id, number, or slug. A wall of
is hard to read; a name is instantly understandable. Ids and URLs don't disappear—they're wrapped in the name's link—but don't replace the name alone.
The Map
The Map is a single issue on this repo's issue tracker with the
label, serving as the canonical artifact. Its tickets are child issues of the map.
The Map is an index, not a store. It lists decisions that have been made and points to the tickets where details are saved; a decision exists in only one place, which is its ticket. Therefore, the Map doesn't repeat details, only provides a gist and a link.
The physical expression of Map, child tickets, blocking, and frontier queries depends on the tracker. Consult the "Wayfinding operations" section of
docs/agents/issue-tracker.md
to learn how this repo expresses them. If that doc doesn't exist, use the local-markdown tracker by default.
The map body
The Map is a low-resolution global view, loaded once per session. Open tickets are not listed in it; they are open child issues found via query.
markdown
## Notes
<domain; skills every session should consult; standing preferences for this effort>
## Decisions so far
<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
- [<closed ticket title>](link) — <one-line gist of the answer>
## Fog
<!-- see "Fog of war" for what belongs here -->
Tickets
Each ticket is a child issue of the map; the tracker's issue id is its identity. The body is a question, sized to fit within a 100K token agent session:
markdown
## Question
<the decision or investigation this ticket resolves>
Each ticket has a
label, with values including
,
,
,
(see
Ticket Types).
A session claims a ticket by assigning it to the dev driving the map before any work begins. This assignee is the claim: only open and unassigned tickets are unclaimed.
Blocking uses the tracker's native dependency relationship; this is important because the tracker UI visualizes the frontier, allowing humans to see which tickets are available without opening the map. Only if the tracker has no native blocking feature should we fall back to body conventions. A ticket becomes unblocked once all its blockers are closed; the frontier refers to open, unblocked, unclaimed child issues—the edge of the known world.
Answers are not written into the body, but recorded upon resolution (see
Work through the map). Assets generated when resolving a ticket are linked from the issue, not pasted into the body.
Ticket Types
- Research: Read documentation, third-party APIs, or local resources like knowledge bases. Create a markdown summary as a linked asset. Use this when knowledge outside the current working directory is needed.
- Prototype: Increase discussion fidelity through cheap, rough, concrete artifacts, such as outlines, rough drafts, stubs, or writing UI/logic code via the /prototype skill. The prototype is linked as an asset. Use this when the core question is "how should it look" or "how should it behave".
- Grilling: Converse with an agent. Use the /grilling and /domain-modeling skills. Ask one question at a time. This is the default type.
- Task: Literal manual work that must be completed before discussion can proceed; there is nothing to decide, prototype, or research. Examples include moving data, registering services, configuring access permissions. The agent automates it if possible; otherwise, provides a precise checklist for humans. Resolve it once completed; record what was done and facts that subsequent tickets depend on (credentials location, new URLs, row counts, etc.).
Fog of war
The Map is intentionally incomplete: don't depict what you can't yet see. Beyond tickets lies the fog: decisions and investigations you sense will come later, but they hang over unresolved questions and can't be pinned down for now. Resolving a ticket clears a patch of fog ahead, elevating questions that can now be defined into new tickets; do this one at a time until the path to the goal is clear and no tickets remain.
The Fog section of the Map is used to record this hazy vision: suspected questions, areas to revisit later, risks that are temporarily postponed. It can be written at whatever granularity your vision allows; it also serves as a signpost for collaborators to understand the direction of this effort.
Fog or ticket? The test is whether you can clearly state the question now, not whether you can answer it now.
- Ticket when the question is clear, even if it's blocked and can't be addressed now.
- Fog when you can't state it that clearly yet. Don't pre-cut fog into ticket-sized pieces: fog is coarser than tickets, and when the frontier reaches it, a patch of fog may elevate into multiple tickets, or none at all.
Fog excludes only content that has already been decided (Decisions so far) and content that is already a ticket.
Invocation
Two modes. Regardless of which mode, never resolve more than one ticket per session.
Chart the map
The user invokes with a loose idea.
- Run and sessions to surface open decisions.
- Create the map (label ): fill in Notes, leave Decisions-so-far empty, and outline the initial Fog.
- Create the tickets you can specify now as child issues of the map, then wire the blocking edges in a second pass (issues need ids before they can reference each other). Wiring will divide them into frontier and blocked tickets; leave anything you can't yet define clearly in Fog.
- Stop. Charting the map is one session's work; do not resolve tickets at the same time.
Work through the map
The user invokes with a map (URL or number). A ticket is optional; if no ticket is provided, you choose the next decision instead of the user.
- Load the map: use the low-resolution view, not the full body of each ticket.
- Select a ticket. Use the one the user names; otherwise, take the first frontier ticket in order. Claim it: assign it to yourself before any work begins.
- Resolve it: zoom as needed, only fetching the full body of relevant or closed tickets when required; invoke the skills mentioned in the block. Use and if unsure.
- Record the resolution: post the answer as a resolution comment, close the issue, and append a context pointer to the map's Decisions-so-far.
- Add newly emerged tickets (create-then-wire); elevate fog that has been clarified by the answer, and clear each elevated patch from the Fog so it exists only as a new ticket. If this decision invalidates other parts of the map, update or delete those tickets.
Users may run unblocked tickets in parallel, so expect other sessions to edit the tracker simultaneously.