Skip to content

Add uncertain-start procedures: diagnosing a bug, prototyping and researching #3797

Closed

Description

@malibio

Overview

The built-in method begins at a known request: Asking the User, then a spec, a plan and tasks. It has no procedure for the work that comes before that, when the problem is a bug nobody has reproduced, a design question an answer to which needs running code, or a fact that has to be found in primary sources. Matt Pocock's skills (MIT) have a procedure for each: diagnosing-bugs, prototype and research.

Problem Statement

  • A defect has to enter through a spec, a plan and a split, or be filed as a bare issue with no diagnosis. Nothing says to reproduce it, minimise it, find the cause and leave a regression test.
  • A design question is answered by asking the user, even when a throwaway prototype would answer it faster. Writing a Spec already allows a prototype snippet but no procedure produces one.
  • A research question has no procedure that ends in cited sources written to the graph.

Proposed Solution

Three procedures, each ending in an artifact the existing flow already consumes:

  • Diagnosing a Bug: reproduce, minimise, hypothesise and test one cause at a time, fix, then guard with a regression test that is seen to fail without the fix. It ends in a plain issue with evidence, or a note on the task being worked.
  • Prototyping: a throwaway built to answer one stated question, discarded afterwards. It ends in a recorded decision (Recording a Decision) that cites what the prototype showed.
  • Researching: a question investigated against primary sources, ending in a cited note on a node the user names or a recorded decision.

Each states when to use it and when to use Asking the User instead.

Documentation

  • ADR-092 planning procedures table - add three rows with source, licence and what changed
  • ADR-094 §3 - a skill is attached to a node or queue; decide where each one is attached and why
  • seeded-nodes.md "Procedure skills" - the count and the list change
  • creating-node-types.md - not needed unless a type is proposed; none is
  • Updates: the ADR-092 table and the seeded-nodes.md procedure list

Architecture Impact

Extends ADR-092's procedures; no new type, field or relationship. Companion nodespace-docs edit required; no new ADR.

Acceptance Criteria

  • Each of the three procedures exists as a seeded skill with a description that says when it applies and when Asking the User applies instead
  • Diagnosing a Bug requires a reproduction and a regression test seen to fail before the fix
  • Prototyping and Researching each end in a recorded decision or a cited note, never in untracked output
  • Each is attached where an agent arrives with that kind of work, with the reason written in the issue or the pull request
  • Attribution lines carry the source, licence and copyright
  • The skill-retrieval confusion matrix includes each new skill and shows no regression for the existing ones
  • An eval:tasks scenario exists for the bug path
  • ADR-092 and seeded-nodes.md are updated in the same change
  • Code passes bun run quality:fix

Technical Specifications

Reference Files

  • packages/agent/src/seeds/skills/ - one markdown file per skill; implementing-a-task.md and writing-a-spec.md for form
  • packages/agent/src/skill_pipeline.rs - the seed table: add a row per skill with its links
  • packages/agent/src/seeds/rules/ - reuse decision-create.md, decision-find-first.md, ask-look-up.md

Implementation Details

Related Issues

Non-Goals

  • A glossary or domain-model procedure (needs a design decision first)
  • Handoff, wayfinder and retrospective procedures

Activity

  1. malibio commented on Oct 14, 2026

    @malibio
    CollaboratorAuthor

    Frontend: 5901 passed (326 files)

  2. self-assigned this
    on Oct 14, 2026
  3. added a commit that references this issue on Oct 14, 2026
    9711839
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions