diff --git a/skills/prototype/SKILL.md b/skills/prototype/SKILL.md index 1d79495..02eddd3 100644 --- a/skills/prototype/SKILL.md +++ b/skills/prototype/SKILL.md @@ -61,11 +61,13 @@ Use the naming convention declared there, or infer it from nearby artifacts when Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it. If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention. -When the caller provides an allocated filename and `parent`, use them exactly and do not advance any counter. -Create only the Prototype artifact and leave the parent artifact unchanged. +When the caller provides an existing ticket artifact path, use it exactly, do not allocate a filename, and complete that artifact in place. Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the prototype. -The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence: +The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence. +When the resolved file is an existing ticket artifact, preserve its workflow metadata and complete the result in that file. + +The branch-appropriate evidence is: - UI evidence uses screenshots. - Logic evidence uses useful code snippets and, where needed, a short interaction transcript. diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index d6cab70..7dfa02b 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -22,11 +22,10 @@ Use the naming convention declared there, or infer it from nearby artifacts when Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it. If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention. -When the caller provides an allocated filename and `parent`, use them exactly and do not advance any counter. -Create only the Research artifact and leave the parent artifact unchanged. +When the caller provides an existing ticket artifact path, use it exactly, do not allocate a filename, and complete that artifact in place. Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the research. -Done when one authoritative output path and its metadata are settled according to the destination convention. +Done when one authoritative Research artifact path and its metadata are settled according to the destination convention. ## 2. Investigate the question @@ -40,6 +39,7 @@ Done when the question is answered as far as primary evidence permits and every ## 3. Write the Research artifact Write the findings to the resolved Markdown file and follow the destination's artifact conventions. +When the resolved file is an existing ticket artifact, preserve its workflow metadata and complete the result in that file. Keep the question, findings, limitations, and citations sufficient for a future reader to evaluate the result without reconstructing the research session. Do not create a source dump or research log. diff --git a/skills/wayfinder/ARTIFACTS.md b/skills/wayfinder/ARTIFACTS.md index 1fd42bb..25f70f6 100644 --- a/skills/wayfinder/ARTIFACTS.md +++ b/skills/wayfinder/ARTIFACTS.md @@ -20,6 +20,8 @@ If no convention can be determined, choose the least surprising lowercase descri Refer to artifacts through the link style used by the destination. Never use a bare identifier as a human-facing reference. +Ticket filenames use the substantive artifact type as their artifact-type suffix: `research`, `prototype`, `grill`, or `task`. +Do not use `ticket` as a filename artifact-type suffix. ## Map @@ -70,7 +72,7 @@ Order Frontier links by the destination's declared ordering unless the user choo Fall back to filename order when no ordering is declared. Under **Decisions so far**, record one concise, self-contained decision for each resolved ticket. -Do not link the ticket or its result artifacts, identify the ticket, or copy supporting detail from the canonical resolution into the map. +Do not link or identify the resolved ticket, or copy supporting detail from the canonical resolution into the map. ## Tickets @@ -108,7 +110,7 @@ An artifact may have many children, which agents find by searching for backlinks `blocked-by` records zero or more upstream artifacts that must resolve before the ticket becomes actionable. It is independent of `parent`. A ticket blocker is satisfied when its status is `resolved`. -A non-ticket result blocker is satisfied when its artifact exists. +A non-ticket blocker is satisfied when its artifact exists. A ticket is on the Frontier when its status is `open`, every blocker is satisfied, and it has no claim. ## Claims and status @@ -130,12 +132,12 @@ An out-of-scope ticket is closed, while **Out of scope** states the excluded wor ## Results -A Grill or Task ticket stores its canonical result under a `## Resolution` section in that ticket. -Research and Prototype tickets leave their question in the ticket and store the result in a child artifact whose `parent` points to the ticket. +A ticket is a self-resolving artifact. +Its canonical result lives in that same artifact rather than in a child result artifact. -When invoking `research` or `prototype`, provide the resolved artifact destination, the filename chosen from that destination's convention, and the ticket link that the result must use as its `parent`. -The called skill creates the result artifact but does not edit the ticket or map. -The coordinating Wayfinder agent validates the returned artifact, marks the ticket resolved, and updates the map. +When invoking `research` or `prototype`, provide the resolved ticket artifact path. +The called skill completes the ticket artifact in place and does not edit the map. +The coordinating Wayfinder agent validates the updated ticket artifact, marks the ticket resolved when the called skill has not already done so, and updates the map. If a called skill cannot honor this artifact contract, leave the ticket unresolved and record the incompatibility instead of silently storing the result elsewhere. Navigate the artifact journey forward by finding every note whose `parent` links to the current artifact. diff --git a/skills/wayfinder/SKILL.md b/skills/wayfinder/SKILL.md index 47be7e7..a301b66 100644 --- a/skills/wayfinder/SKILL.md +++ b/skills/wayfinder/SKILL.md @@ -35,9 +35,9 @@ A HITL ticket only resolves through that exchange. The agent never speaks for the human's side. - **Research** (AFK): Investigate documentation, third-party APIs, or resources outside the current working directory through `research`. - The called skill creates a Research artifact and Wayfinder integrates it. + The called skill completes the Research ticket artifact in place. - **Prototype** (HITL): Raise the fidelity of a logic, state-model, or UI decision through `prototype`. - The called skill creates a Prototype artifact and Wayfinder integrates it after the human reaches a verdict. + The called skill completes the Prototype ticket artifact in place after the human reaches a verdict. - **Grill** (HITL): Resolve a decision through `grill`. This is the default ticket type. - **Task** (AFK or HITL): Perform prerequisite work that must happen before a decision can be made. @@ -86,9 +86,9 @@ Never resolve more than one non-Research ticket in a session. Done when the map is the effort root, every precise question has one ticket, every known blocking edge is represented, and the Frontier is current. 4. **Dispatch Research.** Invoke `research` for each Research ticket using whatever isolation or concurrency the caller provides. - Integrate each returned Research artifact according to [`ARTIFACTS.md`](ARTIFACTS.md). + Reconcile each completed Research ticket according to [`ARTIFACTS.md`](ARTIFACTS.md). Leave a ticket open with the reason visible when its Research run cannot complete. - Done when every dispatched result is integrated or every incomplete Research ticket records why it remains open. + Done when every dispatched Research ticket is resolved or records why it remains open. 5. **Stop.** Stop without resolving a HITL ticket. Done when charting has created and dispatched the visible route without consuming its human decision work. @@ -110,9 +110,9 @@ Never resolve more than one non-Research ticket in a session. Load related artifacts only when needed. Done when the question has a resolution or the prerequisite Task is complete. 4. **Record the resolution.** - Persist the canonical result, resolve the ticket, and append its concise decision under the map's **Decisions so far** according to [`ARTIFACTS.md`](ARTIFACTS.md). - Do not link or identify the resolved ticket or its result artifacts from the map. - Done when the resolution lives in exactly one canonical place and the map states only the resulting decision. + Persist the canonical result in the ticket artifact, resolve the ticket, and append its concise decision under the map's **Decisions so far** according to [`ARTIFACTS.md`](ARTIFACTS.md). + Do not link or identify the resolved ticket from the map. + Done when the resolution lives in the ticket artifact and the map states only the resulting decision. 5. **Advance the frontier.** Create tickets surfaced by the resolution and wire their blockers. Graduate newly precise fog, remove invalidated tickets, move beyond-destination work out of scope, and recompute the Frontier.