From 28c221cdd2ada846382ab4bf584e024b0eba36bc Mon Sep 17 00:00:00 2001 From: Kyle Merritt Date: Wed, 11 Nov 2026 19:20:49 -0500 Subject: [PATCH 1/5] Guide Designer prototypes to hand over the user's own commands The Human answers a prototype's design question by using it as the software's user will, so the prototype method now has the Designer prepare the scenario itself and give the Human the real command, syntax and directory a user would use, with any reset command offered for that purpose alone. Co-Authored-By: Claude Opus 5.5 --- README.md | 3 ++- packages/designer-prototype/SKILL.md | 23 ++++++++++++++++++- .../designer-prototype/relayview-skill.json | 4 ++-- tests/test_packages.py | 2 +- 4 files changed, 27 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 61ca847..503674d 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,8 @@ Public source for RelayView-maintained instruction-only role skills and an illus | `packages/planner-scope` | Maintained default | Planner / planning | 0.2.0 | | `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.2.0 | | `packages/issue-designer-default` | Maintained default | Designer / design | 0.6.1 | -| `packages/designer-wayfinder`, `designer-grilling`, `designer-prototype` | Optional manual guidance | Designer / design | 0.6.0 | +| `packages/designer-wayfinder`, `designer-grilling` | Optional manual guidance | Designer / design | 0.6.0 | +| `packages/designer-prototype` | Optional manual guidance | Designer / design | 0.6.2 | | `packages/designer-research`, `designer-domain-modeling`, `designer-triage` | Optional manual guidance | Designer / design | 0.6.0 | | `packages/designer-to-spec`, `designer-to-tickets` | Optional manual guidance | Designer / design | 0.6.0 | | `packages/codebase-design` | Optional guidance | Planner / planning | 0.3.0 | diff --git a/packages/designer-prototype/SKILL.md b/packages/designer-prototype/SKILL.md index 3f5647c..bfb5d7c 100644 --- a/packages/designer-prototype/SKILL.md +++ b/packages/designer-prototype/SKILL.md @@ -4,9 +4,30 @@ description: Plan a bounded throwaway prototype to answer a design question. disable-model-invocation: true metadata: relayview-display-name: Designer prototype - relayview-version: 0.6.0 + relayview-version: 0.6.2 --- # Prototype Propose the exact question, bounded code or data scope, expected preview or data effects, and limits to the Human before entering this method. Use only owner-admitted prototype controls after agreement. Treat observations as evidence about the question, not production behavior. Record what was tried, observed, and still uncertain; keep throwaway changes out of the issue's implementation claim. + +## Let the Human try it as a user + +The Human answers the question by using the prototype the way the software's user will. The commands they type are part of the design under review: the command name, its arguments and options, and the directory it runs from. + +- Prepare the scenario yourself before handing over. Create the sample data, repositories, and earlier history the question needs, and run any setup steps, so the scenario is ready when the Human arrives. +- Put the scenario's data where the app finds it by default, such as its default config or source directory under HOME, so the user's command needs no extra options. +- Make the Human's first command one the software's user will type: the real command name, the syntax this change proposes, and the arguments a user would pass, run from the directory where a user would be. +- Give each command to try exactly as that user types it, and say what it shows. +- When the scenario needs restoring between tries, give a reset command by its name alone, followed by the user's command to try again. +- Ask the Human about what they saw as a user of the software, in terms of the design question. + +## Before handing over + +Work through this checklist, then give the Human the shell command and the first command to try: + +1. The app's command runs by its own name from `/scratch/bin`: a configured command the owner listed, or a launcher you wrote. Run it with an unknown option from the command directory and confirm its usage message names the command as the user types it. +2. The scenario's data is where the app finds it by default under the workspace's HOME. +3. Helper commands, such as a reset command, are in `/scratch/bin`, so the Human runs each by its name. +4. The command directory is set with `configure` to where the app's user runs the app. +5. You ran the first command to try yourself, exactly as the Human will type it, from that directory, and it showed what the question is about. diff --git a/packages/designer-prototype/relayview-skill.json b/packages/designer-prototype/relayview-skill.json index 8c1d54f..a162995 100644 --- a/packages/designer-prototype/relayview-skill.json +++ b/packages/designer-prototype/relayview-skill.json @@ -2,14 +2,14 @@ "schemaVersion": 1, "source": { "kind": "first-party", - "reference": "v0.6.0" + "reference": "v0.6.2" }, "role": "designer", "step": "design", "files": [ { "path": "SKILL.md", - "sha256": "3898ccf2566614ac3fc54afadd857ebd1e61701d0fe1344b92f79f6b01278706" + "sha256": "e3ce203d245e6a264a0159672610c84032c38bc1dd3892335561fed4e5531eb3" } ] } diff --git a/tests/test_packages.py b/tests/test_packages.py index afa131d..38b555e 100644 --- a/tests/test_packages.py +++ b/tests/test_packages.py @@ -25,7 +25,7 @@ class PackageTests(unittest.TestCase): skill = (package / "SKILL.md").read_text() frontmatter = skill.split("---", 2)[1] self.assertEqual("disable-model-invocation: true" in frontmatter, name in manual) - version = "0.6.1" if name == automatic else "0.6.0" + version = {automatic: "0.6.1", "designer-prototype": "0.6.2"}.get(name, "0.6.0") self.assertIn(f"relayview-version: {version}", frontmatter) manifest = json.loads((package / "relayview-skill.json").read_text()) self.assertEqual(manifest["source"], {"kind": "first-party", "reference": f"v{version}"}) From a968e669c0ca81d8249390409b4a912d3bebcd1f Mon Sep 17 00:00:00 2001 From: Kyle Merritt Date: Thu, 12 Nov 2026 07:52:45 -0500 Subject: [PATCH 2/5] Add guidance-writing questions to the README Co-Authored-By: Claude Opus 5.5 --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 503674d..2ee0043 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,16 @@ To use a user fork, place its closed package directory under the owner's configu To use a maintained Planner or Implementer default, copy its release package under the same trusted root, admit its `SKILL.md` through the owner catalog, then select it for its declared role in Settings. Settings import accepts user-source packages; configure first-party packages in the owner catalog. Select a fork with `source.kind: user` and a distinct ID to replace a Planner or Implementer future assignment. RelayView pins and assigns the Issue Designer default automatically; its optional methods use `workflowPresets.designerSkills`. Planner guidance uses existing read and planning tools; Implementer guidance uses existing implementation and reporting tools. Guidance selection does not change a role's tools, credentials, lifecycle stages, validation requirements, Gitea effects, review, merge, or Human acceptance. The owner keeps the existing Gitea task workflow. +## Write the guidance + +A package's instructions are read by a model, so write them for one. Before adding an instruction, especially in response to behavior seen in a run, ask: + +- Can RelayView's owner determine the result from facts it holds? Then the owner should produce it, and the guidance should use it. +- Does the text state the action to take and a check the agent can run on the result, rather than what to avoid? +- Does the environment the agent works in differ from the familiar one it expects? Name each difference and the action that handles it. + +Judge a change over several runs, using the tool calls each run made, not one successful conversation. RelayView's `docs/authoritative/architecture-heuristics.md`, under "Model-Facing Work", records these defaults in full. + ## Release identity A release tag pins public source. CI runs package checks and archives from that source. RelayView's bundled copy records the source tag and commit plus each package identity and file hash, then verifies the bytes in its own focused test. A bundled update creates a new release identity; it does not overwrite a user fork. From 87ebe1683e569bb881acb9a8fb098edabd4bef75 Mon Sep 17 00:00:00 2001 From: Kyle Merritt Date: Thu, 12 Nov 2026 07:55:50 -0500 Subject: [PATCH 3/5] Have the prototype checklist cd to the command directory Co-Authored-By: Claude Opus 5.5 --- packages/designer-prototype/SKILL.md | 2 +- packages/designer-prototype/relayview-skill.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/designer-prototype/SKILL.md b/packages/designer-prototype/SKILL.md index bfb5d7c..dda39e1 100644 --- a/packages/designer-prototype/SKILL.md +++ b/packages/designer-prototype/SKILL.md @@ -26,7 +26,7 @@ The Human answers the question by using the prototype the way the software's use Work through this checklist, then give the Human the shell command and the first command to try: -1. The app's command runs by its own name from `/scratch/bin`: a configured command the owner listed, or a launcher you wrote. Run it with an unknown option from the command directory and confirm its usage message names the command as the user types it. +1. The app's command runs by its own name from `/scratch/bin`: a configured command the owner listed, or a launcher you wrote. Run `cd` to the command directory, then the command with an unknown option, and confirm its usage message names the command as the user types it. 2. The scenario's data is where the app finds it by default under the workspace's HOME. 3. Helper commands, such as a reset command, are in `/scratch/bin`, so the Human runs each by its name. 4. The command directory is set with `configure` to where the app's user runs the app. diff --git a/packages/designer-prototype/relayview-skill.json b/packages/designer-prototype/relayview-skill.json index a162995..d0ec5e7 100644 --- a/packages/designer-prototype/relayview-skill.json +++ b/packages/designer-prototype/relayview-skill.json @@ -9,7 +9,7 @@ "files": [ { "path": "SKILL.md", - "sha256": "e3ce203d245e6a264a0159672610c84032c38bc1dd3892335561fed4e5531eb3" + "sha256": "53faaae81e3ed97345a0887c7f6d6779f0f1de82d83697e4bf48d3250596658c" } ] } From 5fdb42a8aa102f6c476494296744be58669788fd Mon Sep 17 00:00:00 2001 From: Kyle Merritt Date: Thu, 12 Nov 2026 18:41:46 -0500 Subject: [PATCH 4/5] Add a prototype reset command only when the scenario changes A read-only command such as a dry-run leaves nothing to restore, yet naming a reset command as the example helper led Designers to build one for every prototype. The method and checklist now ask for a reset command only when a command the Human will try changes the scenario. Co-Authored-By: Claude Opus 5.5 --- packages/designer-prototype/SKILL.md | 4 ++-- packages/designer-prototype/relayview-skill.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/designer-prototype/SKILL.md b/packages/designer-prototype/SKILL.md index dda39e1..bf18396 100644 --- a/packages/designer-prototype/SKILL.md +++ b/packages/designer-prototype/SKILL.md @@ -19,7 +19,7 @@ The Human answers the question by using the prototype the way the software's use - Put the scenario's data where the app finds it by default, such as its default config or source directory under HOME, so the user's command needs no extra options. - Make the Human's first command one the software's user will type: the real command name, the syntax this change proposes, and the arguments a user would pass, run from the directory where a user would be. - Give each command to try exactly as that user types it, and say what it shows. -- When the scenario needs restoring between tries, give a reset command by its name alone, followed by the user's command to try again. +- Add a reset command only when a command the Human will try changes the scenario, such as a real update; then put it in `/scratch/bin` and give it by its name alone, followed by the command to try again. - Ask the Human about what they saw as a user of the software, in terms of the design question. ## Before handing over @@ -28,6 +28,6 @@ Work through this checklist, then give the Human the shell command and the first 1. The app's command runs by its own name from `/scratch/bin`: a configured command the owner listed, or a launcher you wrote. Run `cd` to the command directory, then the command with an unknown option, and confirm its usage message names the command as the user types it. 2. The scenario's data is where the app finds it by default under the workspace's HOME. -3. Helper commands, such as a reset command, are in `/scratch/bin`, so the Human runs each by its name. +3. Helper commands are in `/scratch/bin`, so the Human runs each by its name. 4. The command directory is set with `configure` to where the app's user runs the app. 5. You ran the first command to try yourself, exactly as the Human will type it, from that directory, and it showed what the question is about. diff --git a/packages/designer-prototype/relayview-skill.json b/packages/designer-prototype/relayview-skill.json index d0ec5e7..1d35d19 100644 --- a/packages/designer-prototype/relayview-skill.json +++ b/packages/designer-prototype/relayview-skill.json @@ -9,7 +9,7 @@ "files": [ { "path": "SKILL.md", - "sha256": "53faaae81e3ed97345a0887c7f6d6779f0f1de82d83697e4bf48d3250596658c" + "sha256": "0f39f7db296649dba3024bbeaadac9124fdf04c99c246d1f91772bab51d2e795" } ] } From a04e3ed244fca373dea827afa94bd08c8461461a Mon Sep 17 00:00:00 2001 From: Kyle Merritt Date: Thu, 12 Nov 2026 19:41:00 -0500 Subject: [PATCH 5/5] Offer prototype commands only for the design question A Designer met the reset-command condition by offering an optional real update for contrast, then built and debugged a reset helper for it. The method now gives the Human only the commands needed to answer the design question, and asks for a reset command only when one of those changes the scenario. Co-Authored-By: Claude Opus 5.5 --- packages/designer-prototype/SKILL.md | 2 +- packages/designer-prototype/relayview-skill.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/designer-prototype/SKILL.md b/packages/designer-prototype/SKILL.md index bf18396..dc75b4a 100644 --- a/packages/designer-prototype/SKILL.md +++ b/packages/designer-prototype/SKILL.md @@ -19,7 +19,7 @@ The Human answers the question by using the prototype the way the software's use - Put the scenario's data where the app finds it by default, such as its default config or source directory under HOME, so the user's command needs no extra options. - Make the Human's first command one the software's user will type: the real command name, the syntax this change proposes, and the arguments a user would pass, run from the directory where a user would be. - Give each command to try exactly as that user types it, and say what it shows. -- Add a reset command only when a command the Human will try changes the scenario, such as a real update; then put it in `/scratch/bin` and give it by its name alone, followed by the command to try again. +- Give the Human only the commands needed to answer the design question. Add a reset command only when one of those commands changes the scenario; then put it in `/scratch/bin` and give it by its name alone, followed by the command to try again. - Ask the Human about what they saw as a user of the software, in terms of the design question. ## Before handing over diff --git a/packages/designer-prototype/relayview-skill.json b/packages/designer-prototype/relayview-skill.json index 1d35d19..9df8247 100644 --- a/packages/designer-prototype/relayview-skill.json +++ b/packages/designer-prototype/relayview-skill.json @@ -9,7 +9,7 @@ "files": [ { "path": "SKILL.md", - "sha256": "0f39f7db296649dba3024bbeaadac9124fdf04c99c246d1f91772bab51d2e795" + "sha256": "b72f085f33c10ea48f69fbe55c4f364f6a873a8ae2e6baeb8eaf2aaf71df5045" } ] }