@hobin/developer 0.1.11 → 0.1.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -1
- package/REFERENCE_ROUTING.md +9 -0
- package/extensions/compaction-language.ts +5 -3
- package/extensions/developer.ts +11 -3
- package/package.json +1 -1
- package/skills/doctor/SKILL.md +284 -0
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@ Use it when a task may hide product rules, consequential cases, ownership,
|
|
|
7
7
|
compatibility, structural timing, or pass-but-wrong verification. Developer:
|
|
8
8
|
|
|
9
9
|
- turns consequential uncertainty into explicit questions;
|
|
10
|
-
- routes Pi to one of
|
|
10
|
+
- routes Pi to one of eleven focused judgment skills;
|
|
11
11
|
- loads deeper references only when an observable trigger calls for them;
|
|
12
12
|
- keeps implementation, unresolved questions, and verification evidence visible
|
|
13
13
|
on the current session branch.
|
|
@@ -70,6 +70,19 @@ The tests pass after this cache rewrite.
|
|
|
70
70
|
Check what they do not prove before calling it done.
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
+
For a scope-bound existing-code diagnosis and improvement plan, ask for Doctor
|
|
74
|
+
explicitly and name a path, flow, boundary, package, or subsystem when you can:
|
|
75
|
+
|
|
76
|
+
```text
|
|
77
|
+
Run a thorough Doctor review of the checkout request-to-persistence flow.
|
|
78
|
+
Preserve current external behavior, consult every triggered Developer judgment,
|
|
79
|
+
and produce a now/next/observe/leave-alone plan without modifying files.
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
When no useful scope is supplied, Doctor performs a cheap orientation pass and
|
|
83
|
+
proposes one. It distinguishes requested, inspected, and claim scope rather than
|
|
84
|
+
presenting a repository sample as an exhaustive review.
|
|
85
|
+
|
|
73
86
|
## Why Developer
|
|
74
87
|
|
|
75
88
|
Ordinary coding requests often contain decisions that look like implementation
|
|
@@ -118,6 +131,7 @@ and the plausible judgment routes add no useful information.
|
|
|
118
131
|
|
|
119
132
|
| Need | Developer helps Pi… |
|
|
120
133
|
| --- | --- |
|
|
134
|
+
| Diagnose existing code | Bound the review, preserve behavior, consult triggered judgments, and order justified improvements |
|
|
121
135
|
| Clarify a feature | Separate meaning, constraints, examples, and blockers |
|
|
122
136
|
| Model behavior | Enumerate cases, contracts, transitions, and guarantees |
|
|
123
137
|
| Shape code | Expose data, interfaces, collaboration, state, and checks |
|
|
@@ -137,6 +151,7 @@ directly with `/skill:<name>`.
|
|
|
137
151
|
|
|
138
152
|
| Skill | Helps decide |
|
|
139
153
|
| --- | --- |
|
|
154
|
+
| `doctor` | What a bounded existing-code scope must preserve, treat, observe, or leave alone |
|
|
140
155
|
| `specify` | Product meaning, scope, invariants, and blockers |
|
|
141
156
|
| `model` | Cases, contracts, transitions, guarantees, and checks |
|
|
142
157
|
| `sketch` | Data, interfaces, collaboration, flow, state, and code shape |
|
|
@@ -152,6 +167,14 @@ Each skill produces an artifact suited to its question instead of defaulting to
|
|
|
152
167
|
undifferentiated prose. Simple judgments remain compact when prose is genuinely
|
|
153
168
|
clearer.
|
|
154
169
|
|
|
170
|
+
Doctor is an explicit coordination workflow, not the default front door for
|
|
171
|
+
ordinary tasks. It first makes a broad, shallow disposition of every available
|
|
172
|
+
Developer judgment lens inside a declared scope. It then closes so each
|
|
173
|
+
triggered question can run through its owning skill and all reference-policy
|
|
174
|
+
routes supported by observable evidence. A final Doctor route synthesizes those
|
|
175
|
+
owner judgments into a treatment plan; Doctor never reads sibling references or
|
|
176
|
+
replaces their methods with one giant checklist.
|
|
177
|
+
|
|
155
178
|
## Commands
|
|
156
179
|
|
|
157
180
|
| Command | Effect |
|
package/REFERENCE_ROUTING.md
CHANGED
|
@@ -198,6 +198,7 @@ separation behavior, and pass-but-wrong cases.
|
|
|
198
198
|
|
|
199
199
|
| Skill | Policy routes | Shape |
|
|
200
200
|
| --- | --- | --- |
|
|
201
|
+
| `doctor` | none | scope, preservation baseline, universal lens disposition, consultation ledger, diagnosis, and treatment order; owner skills select and apply their own references |
|
|
201
202
|
| `abstraction-review` | `candidate-contract-review`, `failed-candidate-check`, `candidate-calibration` | review, failure localization, or promise-based calibration; no shadow construction |
|
|
202
203
|
| `model` | `condition-space`, `contract-replacement`, `relational-constraints`, `temporal-behavior`, `proof-obligation`, `solver-result-boundary`, `logic-query-semantics`, `planning-model` | one model artifact per uncertainty and stop condition |
|
|
203
204
|
| `sketch` | `data-driven-design`, `data-shape-template`, `composition-by-wishes`, `earned-abstraction`, `generative-recursion`, `accumulator-invariant`, `evidence-preserving-boundary`, `design-levels`, `representation-barrier`, `closure-interface`, `process-resources`, `state-history-order`, `generic-dispatch`, `meaning-preserving-conversion`, `language-semantics`, `runtime-compilation`, `responsibility-collaboration`, `variation-role`, `type-transition`, `selection-creation` | one implementable design question per route, with route-local common kernels only where required |
|
|
@@ -209,6 +210,14 @@ separation behavior, and pass-but-wrong cases.
|
|
|
209
210
|
| `visualize` | none | no packaged reference |
|
|
210
211
|
| `adversarial-eval` | none | no packaged reference |
|
|
211
212
|
|
|
213
|
+
Doctor does not aggregate sibling reference files into its own policy. In a
|
|
214
|
+
thorough Doctor review it dispositions every available skill, closes the Doctor
|
|
215
|
+
triage route, and hands each triggered question to its owner skill. The owner
|
|
216
|
+
route then applies this contract to every independently triggered policy route
|
|
217
|
+
and co-required reference set before Doctor synthesizes the recorded judgments.
|
|
218
|
+
This makes all references eligible without loading unrelated methods or losing
|
|
219
|
+
route-local provenance.
|
|
220
|
+
|
|
212
221
|
The implementation execution profile under `extensions/references/` is selected
|
|
213
222
|
by `execution_profile`, not by skill reference routing, and remains a separate
|
|
214
223
|
contract.
|
|
@@ -264,7 +264,7 @@ export function reconstructCompactionLanguage(
|
|
|
264
264
|
}
|
|
265
265
|
|
|
266
266
|
export function continuityMarkerText(tag: LanguageTag): string {
|
|
267
|
-
return `
|
|
267
|
+
return `Silent control: do not acknowledge or quote this marker; continue the current task. User-visible prose language=${tag}; explicit user language requests win.`;
|
|
268
268
|
}
|
|
269
269
|
|
|
270
270
|
export function continuityContextMessage(
|
|
@@ -295,9 +295,11 @@ export function projectCompactionContinuity<T>(
|
|
|
295
295
|
state: CompactionLanguageState;
|
|
296
296
|
}
|
|
297
297
|
| undefined {
|
|
298
|
-
if (!state.pending) return undefined;
|
|
298
|
+
if (!state.pending || state.pending.injected) return undefined;
|
|
299
|
+
// Pi presents custom messages to the model as user messages. Prepend this
|
|
300
|
+
// one-shot control so the retained task remains the latest request.
|
|
299
301
|
return {
|
|
300
|
-
messages: [
|
|
302
|
+
messages: [continuityContextMessage(state.pending, timestamp), ...messages],
|
|
301
303
|
state: markContinuityInjected(state),
|
|
302
304
|
};
|
|
303
305
|
}
|
package/extensions/developer.ts
CHANGED
|
@@ -515,6 +515,9 @@ function protocolPrompt(
|
|
|
515
515
|
"Developer protocol is active.",
|
|
516
516
|
"- Use the default topology as a conditional backbone, not a rigid lifecycle: clarify meaning when needed -> model consequential cases -> sketch the first implementation surface for new behavior or signal the smallest structural movement in existing code -> execute one implementation step -> verify current claims.",
|
|
517
517
|
"- Adapt away from that topology when evidence makes a stage not applicable, but never jump directly from a resolved model to mutation: use sketch for feature implementation or signal for existing-code structural movement first.",
|
|
518
|
+
"- Route doctor only for an explicitly requested scope-bound diagnosis and improvement plan across several judgment kinds; it is not a mandatory prelude, pull-request review, environment check, or synonym for ordinary implementation.",
|
|
519
|
+
"- A thorough Doctor review is broad and shallow before it is narrow and deep: establish requested, inspected, and claim scope; disposition every other available Developer skill with evidence; close Doctor triage; route every triggered distinct consultation to its owning skill; let that owner select and apply every triggered policy route and co-required reference; then return to Doctor to synthesize diagnosis and treatment order. Doctor must not load sibling references or flatten their methods into one checklist.",
|
|
520
|
+
"- While Doctor consultations remain, keep one agent-owned before-completion synthesis question and update its remaining consultation evidence after each owner judgment; do not open one pending question per lens. Resolve it only in the final Doctor synthesis route.",
|
|
518
521
|
"- Route by the requested work product, not keywords: use sketch to create an original caller-facing interface, representation boundary, ownership map, or collaboration; use abstraction-review only when a concrete candidate surface already exists to keep/revise/split/reject/defer; use model first only when unresolved cases, rules, or policy can materially change that surface.",
|
|
519
522
|
`- Call ${ROUTE_TOOL} for exactly one concrete judgment or one green-to-green implementation movement.`,
|
|
520
523
|
"- Use target=implementation only when the next local movement, stable landing, narrow verification, and invariant handling are already justified; otherwise choose the focused skill whose scope fits the current question.",
|
|
@@ -1032,11 +1035,11 @@ export default async function developer(pi: ExtensionAPI) {
|
|
|
1032
1035
|
name: ROUTE_TOOL,
|
|
1033
1036
|
label: "Developer Route Question",
|
|
1034
1037
|
description:
|
|
1035
|
-
"Route one concrete judgment or one green-to-green implementation movement. Route by work product: sketch creates an original design surface, abstraction-review judges an already-shaped candidate, and model settles unresolved conditions before design. Implementation must declare how invariant-bearing values are constructed without unchecked narrowing. Then use stable landings and verify before completion.",
|
|
1038
|
+
"Route one concrete judgment or one green-to-green implementation movement. Route by work product: doctor coordinates an explicitly requested scope-bound existing-code diagnosis, sketch creates an original design surface, abstraction-review judges an already-shaped candidate, and model settles unresolved conditions before design. Implementation must declare how invariant-bearing values are constructed without unchecked narrowing. Then use stable landings and verify before completion.",
|
|
1036
1039
|
promptSnippet: "Choose how to handle one development question",
|
|
1037
1040
|
promptGuidelines: [
|
|
1038
1041
|
`Call ${ROUTE_TOOL} only when there is no active Developer route.`,
|
|
1039
|
-
`Use ${ROUTE_TOOL} with the most focused skill supported by current evidence; choose sketch for an original interface or boundary, abstraction-review only for an already-shaped candidate, and model only for unresolved condition space. target=implementation requires one movement, one stable landing, one narrow verification, and a truthful invariant_handling declaration. Validation followed by an assertion is not an evidence-preserving boundary.`,
|
|
1042
|
+
`Use ${ROUTE_TOOL} with the most focused skill supported by current evidence; choose doctor only for an explicit scope-bound existing-code diagnosis and improvement plan, choose sketch for an original interface or boundary, abstraction-review only for an already-shaped candidate, and model only for unresolved condition space. target=implementation requires one movement, one stable landing, one narrow verification, and a truthful invariant_handling declaration. Validation followed by an assertion is not an evidence-preserving boundary.`,
|
|
1040
1043
|
`When ${ROUTE_TOOL} follows an implementation judgment with another implementation route, cite the previous landing in known_evidence and record plausible skill routes in alternatives_considered instead of selecting implementation by momentum.`,
|
|
1041
1044
|
`After a resolved model, use sketch for first feature implementation framing or signal for existing-code structural movement before implementation mutation.`,
|
|
1042
1045
|
],
|
|
@@ -1261,6 +1264,11 @@ export default async function developer(pi: ExtensionAPI) {
|
|
|
1261
1264
|
`Reference contract: choose policy routes by observable trigger, use ${REFERENCE_TOOL} for every reference in each selected route's co-required set, and provide reference_basis for every loaded path; use reference_exemption only when no policy route applies.`,
|
|
1262
1265
|
]
|
|
1263
1266
|
: []),
|
|
1267
|
+
...(skill && event.availableReferences.length === 0
|
|
1268
|
+
? [
|
|
1269
|
+
"Reference contract: this skill has no packaged references; omit both reference_basis and reference_exemption from its judgment.",
|
|
1270
|
+
]
|
|
1271
|
+
: []),
|
|
1264
1272
|
`Known evidence: ${event.knownEvidence.length > 0 ? event.knownEvidence.join(" | ") : "none"}`,
|
|
1265
1273
|
`Alternatives reconsidered: ${
|
|
1266
1274
|
event.consideredAlternatives.length > 0
|
|
@@ -1773,7 +1781,7 @@ export default async function developer(pi: ExtensionAPI) {
|
|
|
1773
1781
|
promptGuidelines: [
|
|
1774
1782
|
`Use ${JUDGMENT_TOOL} with the exact active Developer route ID.`,
|
|
1775
1783
|
`Use ${JUDGMENT_TOOL} result as Markdown and preserve the routed skill's inspectable tables, diagrams, matrices, timelines, and code blocks instead of reducing them to prose.`,
|
|
1776
|
-
`For a resolved skill route with available references, use ${JUDGMENT_TOOL} reference_basis to connect each relied-on ${REFERENCE_TOOL} load to its trigger, applied rule, and resulting artifact, or use reference_exemption when no reference is relevant. Never provide both.`,
|
|
1784
|
+
`For a resolved skill route with available references, use ${JUDGMENT_TOOL} reference_basis to connect each relied-on ${REFERENCE_TOOL} load to its trigger, applied rule, and resulting artifact, or use reference_exemption when no reference is relevant. Never provide both. For a skill with no packaged references, omit both fields.`,
|
|
1777
1785
|
`Use ${JUDGMENT_TOOL} open_questions with resolution_owner, gate, and resolution_criteria. User-owned gated questions require explanatory context before controls; for finite required decisions, add a choice-form response_spec with one field per decision. Use question_updates whenever current evidence settles or changes any existing pending question.`,
|
|
1778
1786
|
`Do not use ${JUDGMENT_TOOL} with resolved, not-applicable, or blocked status without at least one concrete basis.`,
|
|
1779
1787
|
],
|
package/package.json
CHANGED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: doctor
|
|
3
|
+
description: "Diagnose a user-selected or explicitly bounded existing codebase scope and produce an evidence-backed improvement plan. Use for repository, package, directory, module, runtime-flow, boundary, or feature-slice review when behavior to preserve, invariant risk, structural pressure, evidence gaps, and justified now/next/later/leave-alone work must be assessed together. Not for pull-request diff review, environment setup checks, speculative cleanup, or automatic repair."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Doctor
|
|
7
|
+
|
|
8
|
+
Diagnose one bounded existing-code scope, consult the focused Developer judgments
|
|
9
|
+
that its evidence actually triggers, and synthesize a treatment plan without
|
|
10
|
+
turning age, style, or code smells into disease.
|
|
11
|
+
|
|
12
|
+
## Core Question
|
|
13
|
+
|
|
14
|
+
Within this explicit codebase scope, what must be preserved, what is at risk or
|
|
15
|
+
obstructing change, and what should be treated now, prepared next, observed, or
|
|
16
|
+
left alone?
|
|
17
|
+
|
|
18
|
+
## Judgment Spine
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
requested target and change horizon
|
|
22
|
+
-> requested / inspected / claim scope
|
|
23
|
+
-> behavior-preservation baseline
|
|
24
|
+
-> broad, shallow disposition of every Developer judgment lens
|
|
25
|
+
-> narrow, deep owner-skill consultations and triggered references
|
|
26
|
+
-> evidence-backed mechanisms and treatment candidates
|
|
27
|
+
-> treat-now | prepare-next | observe | leave-alone | needs-decision
|
|
28
|
+
-> first concrete handoff
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Doctor is broad in lens coverage and bounded in code coverage. It is not a fixed
|
|
32
|
+
prelude for ordinary tasks.
|
|
33
|
+
|
|
34
|
+
## Inputs
|
|
35
|
+
|
|
36
|
+
- User-selected target, or evidence sufficient to propose one
|
|
37
|
+
- Repository structure, entry points, callers, runtime flows, and public boundaries
|
|
38
|
+
- Accepted behavior, tests, traces, incidents, schemas, and compatibility evidence
|
|
39
|
+
- Current change pressure and intended horizon when available
|
|
40
|
+
- Explicit review depth, lenses, exclusions, and evidence budget
|
|
41
|
+
|
|
42
|
+
## Scope Contract
|
|
43
|
+
|
|
44
|
+
Establish scope before diagnosis. Separate what was requested from what was
|
|
45
|
+
actually inspected and from the area to which conclusions may apply.
|
|
46
|
+
|
|
47
|
+
| Field | Required meaning |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| Requested target | What the user asked Doctor to review |
|
|
50
|
+
| Selected scope | Path, symbol, runtime flow, boundary, feature slice, subsystem, or repository sample |
|
|
51
|
+
| Included | Concrete paths, symbols, entry points, flows, or collaborators admitted |
|
|
52
|
+
| Excluded | Nearby areas this review does not cover |
|
|
53
|
+
| Depth | `local`, `collaborators`, `flow`, `subsystem`, or `repository-sample` |
|
|
54
|
+
| Lenses | Requested concerns, or `balanced` when no concern dominates |
|
|
55
|
+
| Evidence budget | Bounded files, history, commands, traces, or sampling rule |
|
|
56
|
+
| Inspected scope | Evidence actually read or executed |
|
|
57
|
+
| Claim boundary | The largest area current evidence can support conclusions about |
|
|
58
|
+
|
|
59
|
+
If the user did not select a useful scope, perform only a cheap orientation pass:
|
|
60
|
+
inspect manifests, subsystem boundaries, entry points, current failures or
|
|
61
|
+
requests, recent change pressure, dependency hubs, and irreversible effects.
|
|
62
|
+
Then propose the smallest valuable scope with evidence. Do not call an
|
|
63
|
+
orientation sample a whole-repository diagnosis.
|
|
64
|
+
|
|
65
|
+
A dependency outside scope may be inspected when the declared depth includes it.
|
|
66
|
+
Otherwise present a scope-expansion candidate with the trigger, added surface,
|
|
67
|
+
expected value, and cost. Never expand recursively by curiosity.
|
|
68
|
+
|
|
69
|
+
## Review Mode
|
|
70
|
+
|
|
71
|
+
Use `thorough-within-scope` unless the user explicitly asks for a faster pass.
|
|
72
|
+
|
|
73
|
+
- `quick`: inspect the strongest observable risk and label all omitted lenses and
|
|
74
|
+
code surfaces as unreviewed;
|
|
75
|
+
- `standard`: disposition every Developer lens, then deepen only the
|
|
76
|
+
highest-consequence or currently pressured consultations;
|
|
77
|
+
- `thorough-within-scope`: disposition every available Developer lens, route
|
|
78
|
+
every triggered distinct consultation, inspect every policy-route trigger in
|
|
79
|
+
each selected owner skill, and apply every reference required by every
|
|
80
|
+
selected route.
|
|
81
|
+
|
|
82
|
+
Exhaustiveness applies to judgment coverage inside the claim boundary, not to
|
|
83
|
+
unbounded file traversal or unsupported whole-system claims.
|
|
84
|
+
|
|
85
|
+
## Evidence Order
|
|
86
|
+
|
|
87
|
+
Prefer evidence in this order while keeping disagreements visible:
|
|
88
|
+
|
|
89
|
+
1. accepted user or product contract;
|
|
90
|
+
2. observed externally meaningful behavior, production trace, incident, or
|
|
91
|
+
compatibility obligation;
|
|
92
|
+
3. executable tests and fixtures whose observers match the claim;
|
|
93
|
+
4. callers, state transitions, persisted representations, and effect order;
|
|
94
|
+
5. implementation structure and static relationships;
|
|
95
|
+
6. history, churn, coverage counts, complexity, and code smells as scope or
|
|
96
|
+
pressure clues only.
|
|
97
|
+
|
|
98
|
+
A smell becomes a finding only when it is connected to a behavior, invariant,
|
|
99
|
+
change cost, failure mode, evidence gap, or compatibility consequence. Age,
|
|
100
|
+
language fashion, low coverage, duplication, or a long function alone does not
|
|
101
|
+
justify treatment.
|
|
102
|
+
|
|
103
|
+
## Preservation Baseline
|
|
104
|
+
|
|
105
|
+
Before finding defects, record behavior and obligations that treatment must not
|
|
106
|
+
break.
|
|
107
|
+
|
|
108
|
+
| Behavior or contract | Owner / observers | Evidence | Confidence | Failure consequence |
|
|
109
|
+
| --- | --- | --- | --- | --- |
|
|
110
|
+
|
|
111
|
+
Cover relevant public APIs, critical user flows, persisted or legacy data,
|
|
112
|
+
external input boundaries, state transitions, effect order, failure and retry
|
|
113
|
+
behavior, and compatibility surfaces. Record `baseline evidence gap` when an
|
|
114
|
+
important obligation has no distinguishing observer; do not silently treat it
|
|
115
|
+
as absent.
|
|
116
|
+
|
|
117
|
+
## Universal Lens Sweep
|
|
118
|
+
|
|
119
|
+
In `standard` and `thorough-within-scope`, give every available Developer skill
|
|
120
|
+
other than Doctor one disposition: `triggered`, `no-trigger`, `needs-evidence`,
|
|
121
|
+
`out-of-scope`, or `blocked`. Each disposition requires concrete scope evidence.
|
|
122
|
+
|
|
123
|
+
| Owner skill | Diagnostic question | Representative trigger |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| `specify` | Is code deciding unresolved product meaning or scope? | docs, tests, callers, or defaults imply different product senses |
|
|
126
|
+
| `model` | Are admitted, forbidden, absent, replacement, relational, or temporal conditions unsettled? | null/default/legacy combinations, invalid states, retries, ordering, solver or query semantics |
|
|
127
|
+
| `sketch` | Is an implementable owner, boundary, representation, data flow, state flow, or collaboration missing? | unchecked narrowing, shotgun parsing, navigation leaks, mixed effects, repeated ownership decisions |
|
|
128
|
+
| `signal` | Is observable structural movement present rather than mere similarity? | repeated change, closest parallel cases, model-code mismatch, boundary pressure |
|
|
129
|
+
| `naming-judgment` | Do names preserve stable domain sense and expose consequential effects? | filler names, effect-hiding verbs, implementation-shaped names, sense collisions |
|
|
130
|
+
| `abstraction-review` | Can callers safely rely on an already-shaped helper, API, interface, boundary, or workflow rule? | a concrete candidate makes unstable or leaking promises |
|
|
131
|
+
| `schedule` | When does a stable concrete structural candidate belong? | current invariant pressure, nested work, delay cost, or lost reversibility |
|
|
132
|
+
| `verify` | What do current checks prove, and what plausible wrong shape still passes? | green checks with observer, source, branch, construction-path, or effect-order gaps |
|
|
133
|
+
| `adversarial-eval` | Does a consequential claim need escalating finite counterexamples? | ordinary checks can pass while security, data, compatibility, or workflow behavior is wrong |
|
|
134
|
+
| `visualize` | Would a visual surface materially lower the cost of judging relationships? | state, ownership, flow, dependency, or ordering is hard to inspect in prose |
|
|
135
|
+
|
|
136
|
+
Use this inspection surface:
|
|
137
|
+
|
|
138
|
+
| Skill | Disposition | Scope evidence | Concrete consultation question or exemption |
|
|
139
|
+
| --- | --- | --- | --- |
|
|
140
|
+
|
|
141
|
+
`no-trigger` means observed evidence makes the compact question irrelevant here;
|
|
142
|
+
it does not mean the entire codebase is healthy. `needs-evidence` names the
|
|
143
|
+
smallest observation that could change the disposition.
|
|
144
|
+
|
|
145
|
+
## Consultation Workflow
|
|
146
|
+
|
|
147
|
+
Doctor does not impersonate all other skills and must not read sibling skill
|
|
148
|
+
references inside a Doctor route.
|
|
149
|
+
|
|
150
|
+
For every `triggered` disposition:
|
|
151
|
+
|
|
152
|
+
1. write one concrete consultation question and its trigger evidence;
|
|
153
|
+
2. close the Doctor triage route;
|
|
154
|
+
3. route the question to its owning Developer skill;
|
|
155
|
+
4. inspect every reference-policy route in that skill;
|
|
156
|
+
5. select every route whose observable trigger answers a distinct unresolved
|
|
157
|
+
question;
|
|
158
|
+
6. load and apply every co-required reference in the declared order;
|
|
159
|
+
7. preserve the owner skill's artifact, stop, separation boundary, and
|
|
160
|
+
`reference_basis`;
|
|
161
|
+
8. return to Doctor only after consultations resolve or become explicit gaps.
|
|
162
|
+
|
|
163
|
+
Use dependency only when evidence requires it: unresolved meaning or condition
|
|
164
|
+
space precedes a design that depends on it; `signal` precedes promotion of a
|
|
165
|
+
new structural candidate; `sketch` creates an original surface;
|
|
166
|
+
`abstraction-review` judges an existing surface; `schedule` requires a stable
|
|
167
|
+
candidate; `verify` and `adversarial-eval` challenge the resulting claims. Do
|
|
168
|
+
not run this as a mandatory phase sequence when a lens is `no-trigger`.
|
|
169
|
+
|
|
170
|
+
When Developer protocol is active and consultations remain, keep one
|
|
171
|
+
agent-owned `before-completion` Doctor synthesis question rather than opening one
|
|
172
|
+
pending question per lens. Owner-skill judgments may resolve their narrow
|
|
173
|
+
question while retaining that synthesis question with updated remaining work.
|
|
174
|
+
The final Doctor route resolves it after integrating the consultation ledger.
|
|
175
|
+
|
|
176
|
+
Use a consultation ledger:
|
|
177
|
+
|
|
178
|
+
| Skill / policy route | Trigger evidence | Judgment artifact | Result | Residual gap |
|
|
179
|
+
| --- | --- | --- | --- | --- |
|
|
180
|
+
|
|
181
|
+
## Diagnosis
|
|
182
|
+
|
|
183
|
+
Synthesize consultations into findings without erasing disagreement or evidence
|
|
184
|
+
limits.
|
|
185
|
+
|
|
186
|
+
| ID | Observation | Consequence | Mechanism | Evidence | Confidence | Affected scope | Owner judgment |
|
|
187
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
188
|
+
|
|
189
|
+
A valid diagnosis names:
|
|
190
|
+
|
|
191
|
+
- the observable behavior, invariant risk, change obstruction, or evidence gap;
|
|
192
|
+
- the mechanism connecting code shape to that consequence;
|
|
193
|
+
- supporting and contradicting evidence;
|
|
194
|
+
- confidence and the exact claim boundary;
|
|
195
|
+
- the smallest plausible falsifier;
|
|
196
|
+
- a concrete candidate only when enough meaning and shape are stable.
|
|
197
|
+
|
|
198
|
+
Do not merge independent findings merely because one treatment could touch the
|
|
199
|
+
same files.
|
|
200
|
+
|
|
201
|
+
## Treatment Plan
|
|
202
|
+
|
|
203
|
+
Use ordinal decisions rather than pseudo-precise health scores.
|
|
204
|
+
|
|
205
|
+
| Candidate | Diagnosis | Behavior to preserve | Guarantee gained | Current pressure | Dependencies / reversibility | Stable landing | Verifier | Decision |
|
|
206
|
+
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
207
|
+
|
|
208
|
+
Decide:
|
|
209
|
+
|
|
210
|
+
- `treat-now`: current correctness, security, data, compatibility, or invariant
|
|
211
|
+
risk justifies the smallest stable treatment;
|
|
212
|
+
- `prepare-next`: the treatment is needed before the next related change to
|
|
213
|
+
avoid nested work or prevent a known recurrence;
|
|
214
|
+
- `observe`: current pressure is insufficient; record an observable reopen
|
|
215
|
+
condition;
|
|
216
|
+
- `leave-alone`: treatment is speculative, destroys useful freedom, or costs
|
|
217
|
+
more than the evidenced problem;
|
|
218
|
+
- `needs-decision`: product, operational, or risk ownership cannot be inferred.
|
|
219
|
+
|
|
220
|
+
Do not turn the treatment plan into a predetermined multi-step implementation
|
|
221
|
+
queue. Provide one first handoff with its owner skill, preserved behavior,
|
|
222
|
+
smallest stable landing, narrow verifier, and explicitly deferred work. Reobserve
|
|
223
|
+
and reroute after that landing.
|
|
224
|
+
|
|
225
|
+
## Output
|
|
226
|
+
|
|
227
|
+
Lead with scope and the user's actual change or risk, not a health score. A
|
|
228
|
+
resolved Doctor report contains:
|
|
229
|
+
|
|
230
|
+
1. Doctor scope and actual coverage;
|
|
231
|
+
2. preservation baseline;
|
|
232
|
+
3. all required lens dispositions;
|
|
233
|
+
4. consultation ledger with policy-route and reference provenance;
|
|
234
|
+
5. diagnosis table;
|
|
235
|
+
6. treatment plan;
|
|
236
|
+
7. first concrete handoff and residual unknowns;
|
|
237
|
+
8. an ASCII flow, ownership, state, or dependency map when relationships are
|
|
238
|
+
materially consequential.
|
|
239
|
+
|
|
240
|
+
When used inside a larger task, return:
|
|
241
|
+
|
|
242
|
+
```text
|
|
243
|
+
Status: resolved | needs-evidence | not-applicable | blocked
|
|
244
|
+
Result: scope-bound diagnosis and treatment order, or the consultation plan still required
|
|
245
|
+
Basis: inspected code, behavior, callers, tests, traces, history, and owner-skill judgments
|
|
246
|
+
Open questions: unresolved consultations, scope choices, product decisions, or none
|
|
247
|
+
Artifacts: scope/coverage map, preservation baseline, lens matrix, consultation ledger, findings, treatment plan, and first handoff
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Return only Doctor's scope, triage, or synthesis judgment for the current route;
|
|
251
|
+
leave owner-skill consultation and implementation routing to the caller.
|
|
252
|
+
|
|
253
|
+
## Completion
|
|
254
|
+
|
|
255
|
+
A `thorough-within-scope` diagnosis is resolved only when:
|
|
256
|
+
|
|
257
|
+
- requested, selected, inspected, and claim scopes are explicit;
|
|
258
|
+
- every available non-Doctor skill has an evidence-backed disposition;
|
|
259
|
+
- every triggered consultation is resolved or retained as an explicit gap;
|
|
260
|
+
- every selected owner-skill policy route loaded and applied all required
|
|
261
|
+
references;
|
|
262
|
+
- every finding has an observable consequence, mechanism, evidence, confidence,
|
|
263
|
+
scope, and falsifier;
|
|
264
|
+
- every treatment preserves named behavior and has an owner and verifier;
|
|
265
|
+
- every `treat-now` item has a smallest stable landing;
|
|
266
|
+
- every `observe` item has a reopen condition;
|
|
267
|
+
- intentionally unchanged areas are visible.
|
|
268
|
+
|
|
269
|
+
Return `needs-evidence` after triage when owner-skill consultations, a baseline
|
|
270
|
+
observer, or bounded repository evidence can settle the diagnosis. Return
|
|
271
|
+
`blocked` when required product, operational, access, or risk ownership cannot
|
|
272
|
+
be obtained. Return `not-applicable` when the request is a local diff review,
|
|
273
|
+
environment check, already-shaped single judgment, or implementation task better
|
|
274
|
+
owned directly by another skill.
|
|
275
|
+
|
|
276
|
+
## Boundary
|
|
277
|
+
|
|
278
|
+
Do not implement treatment, automatically repair files, recommend a rewrite
|
|
279
|
+
because code is old, equate style or metrics with risk, invent product meaning,
|
|
280
|
+
promote every duplication into an abstraction, flatten sibling skills into a
|
|
281
|
+
checklist, load all references without triggers, or claim coverage beyond the
|
|
282
|
+
inspected scope. Doctor owns scope, lens coverage, consultation planning,
|
|
283
|
+
diagnostic synthesis, and treatment ordering; focused Developer skills own the
|
|
284
|
+
actual judgments and their routed references.
|