@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 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 ten focused judgment skills;
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 |
@@ -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 `Post-compaction continuity: user-visible prose language=${tag}; explicit language requests win.`;
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: [...messages, continuityContextMessage(state.pending, timestamp)],
302
+ messages: [continuityContextMessage(state.pending, timestamp), ...messages],
301
303
  state: markContinuityInjected(state),
302
304
  };
303
305
  }
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hobin/developer",
3
- "version": "0.1.11",
3
+ "version": "0.1.12",
4
4
  "description": "Branch-aware judgment routing, evidence gates, and focused development skills for Pi.",
5
5
  "type": "module",
6
6
  "keywords": ["pi-package", "pi", "developer", "skills"],
@@ -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.