Compare commits
3 Commits
b5c6e33730
...
99df169fbd
| Author | SHA1 | Date | |
|---|---|---|---|
| 99df169fbd | |||
| 8035e0e436 | |||
| 012a4bfd1e |
@@ -76,14 +76,17 @@ If the host project has no task runner, put the command at the top of the protot
|
||||
|
||||
Done when a fresh user can launch the prototype with one documented command.
|
||||
|
||||
### 6. Hand it over
|
||||
### 6. Evaluate it
|
||||
|
||||
Give the user the run command.
|
||||
In HITL mode, give the user the run command.
|
||||
They drive it themselves.
|
||||
The interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" because those expose bugs in the idea.
|
||||
Add actions when the feedback needs them.
|
||||
|
||||
Done when the user can exercise the model and the prototype exposes every state transition needed to reach a verdict.
|
||||
In AFK mode, run the command yourself and drive the hard cases that answer the stated question.
|
||||
Record the observations that support the verdict.
|
||||
|
||||
Done when the evaluator can exercise the model and the prototype exposes every state transition needed to reach a verdict.
|
||||
|
||||
## Production mapping
|
||||
|
||||
|
||||
@@ -7,6 +7,9 @@ description: Build a throwaway prototype to answer a design question. Use when t
|
||||
|
||||
A prototype is **throwaway code that answers one question**.
|
||||
The question decides the branch.
|
||||
The interaction mode decides who reaches the verdict.
|
||||
Use AFK mode when the question has objective observable criteria the agent can test end to end.
|
||||
Use HITL mode when the verdict depends on human judgment, taste, or UX feel.
|
||||
|
||||
## 1. Pick a branch
|
||||
|
||||
@@ -39,11 +42,13 @@ Done when exactly one branch and one design question govern the prototype.
|
||||
|
||||
## 2. Build and reach a verdict
|
||||
|
||||
Follow the selected branch through its handover step and iterate on the prototype in response to the user's feedback.
|
||||
Follow the selected branch through its evaluation step.
|
||||
In HITL mode, hand the prototype to the user and iterate in response to their feedback.
|
||||
In AFK mode, run the prototype yourself and evaluate the objective observations against the question.
|
||||
Do not treat a runnable prototype as the result.
|
||||
The result is the verdict that answers the design question.
|
||||
|
||||
Done when the user has reached an explicit verdict or stated that the prototype did not resolve the question.
|
||||
Done when the verdict is explicit, or when the prototype establishes that it did not resolve the question.
|
||||
|
||||
## 3. Capture the primary source
|
||||
|
||||
@@ -61,11 +66,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.
|
||||
|
||||
@@ -99,12 +99,15 @@ Put the switcher in a single shared component so both sub-shapes can reuse it. L
|
||||
|
||||
Done when mouse and keyboard controls cycle through every shareable variant without intercepting text-editing keys, and the switcher cannot render in production.
|
||||
|
||||
### 5. Hand it over
|
||||
### 5. Evaluate it
|
||||
|
||||
Surface the URL and the `?variant=` keys.
|
||||
In HITL mode, surface the URL and the `?variant=` keys.
|
||||
The user flips through the variants and may combine elements rather than choosing one unchanged.
|
||||
|
||||
Done when the user can compare every variant in its host context and the prototype exposes enough contrast to reach a verdict.
|
||||
In AFK mode, open the URL yourself, compare every variant against the stated objective criteria, and record the observations that support the verdict.
|
||||
Use HITL instead when the decision depends on taste, product judgment, or UX feel.
|
||||
|
||||
Done when the evaluator can compare every variant in its host context and the prototype exposes enough contrast to reach a verdict.
|
||||
|
||||
## Production mapping
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -95,7 +97,8 @@ tags:
|
||||
Use one of these tags:
|
||||
|
||||
- `ticket/research`
|
||||
- `ticket/prototype`
|
||||
- `ticket/prototype/afk`
|
||||
- `ticket/prototype/hitl`
|
||||
- `ticket/grill`
|
||||
- `ticket/task/afk`
|
||||
- `ticket/task/human`
|
||||
@@ -108,7 +111,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 +133,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.
|
||||
|
||||
@@ -35,9 +35,11 @@ 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.
|
||||
- **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 Research ticket artifact in place.
|
||||
- **Prototype** (AFK or HITL): Raise the fidelity of a logic, state-model, or UI decision through `prototype`.
|
||||
Use AFK when the question has objective observable criteria the agent can test end to end.
|
||||
Use HITL when the verdict depends on human judgment, taste, or UX feel.
|
||||
The called skill completes the Prototype ticket artifact in place after the verdict is reached.
|
||||
- **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.
|
||||
@@ -69,7 +71,9 @@ Do not record a scope boundary as a decision on the route.
|
||||
- A loose idea without a map uses **Chart the map**.
|
||||
- An existing map uses **Work through the map**.
|
||||
|
||||
Never resolve more than one non-Research ticket in a session.
|
||||
A delegated worker resolves exactly one claimed ticket and stops.
|
||||
An interactive or coordinating Wayfinder session may resolve multiple tickets sequentially, but must complete the full reconcile, claim, resolve, record, and frontier-advance loop before selecting another ticket.
|
||||
Do not auto-consume HITL tickets without user participation.
|
||||
|
||||
## Chart the map
|
||||
|
||||
@@ -86,9 +90,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,15 +114,17 @@ 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.
|
||||
Re-read shared artifacts before each write because other sessions may edit the effort concurrently.
|
||||
Done when every newly visible question has exactly one home and the map agrees with all current ticket metadata.
|
||||
6. **Complete or stop.**
|
||||
6. **Complete, continue, or stop.**
|
||||
When no unresolved tickets or fog remain, mark the map complete and stop for an explicit handoff instruction.
|
||||
In a delegated worker session, stop after one ticket is resolved and the frontier is advanced.
|
||||
In an interactive or coordinating session, continue to another Frontier ticket only after reconciling the map and shared artifacts again.
|
||||
Otherwise stop.
|
||||
Done when the map records its current lifecycle state and no destination work has begun without permission.
|
||||
|
||||
Reference in New Issue
Block a user