1# Software Adaptation
2 
3How VM phases land as engineering artifacts. Use this when the problem is code-shaped.
4 
5## Phase -> artifact mapping
6 
7| VM phase | Engineering artifact |
8|---|---|
9| Frame | One-paragraph problem statement + linked issue/PR |
10| Information | Inspection notes: file paths, line refs, log excerpts, telemetry queries, prior ADRs |
11| Function analysis | Function map (verb+noun) tied to user roles and components |
12| Creative | Options list including: no-build, config-only, UI-only, contract-only (backend), instrumentation-first, manual/operational, full build |
13| Evaluation | Options Matrix with software criteria (see `evaluation-matrix.md`) |
14| Development | PRD or ADR with diagrams + interface sketches |
15| Risk | Risk register with detection + mitigation + owner (see `risk-register.md`) |
16| Recommendation | ADR-style recommendation: status, context, decision, consequences, alternatives |
17| Implementation slice | Issue list, each with: scope, exit criteria, observability, rollback, dependencies |
18| Feedback / POE | Post-release check: telemetry diff vs predicted value, lessons captured into ADR |
19 
20## Information sources to inspect before asking
21 
22- Repo: directory layout, package boundaries, existing patterns nearby.
23- Recent PRs touching the area; their reviews and rejected approaches.
24- ADRs in `docs/adr/` (or equivalent).
25- Issue tracker for the same surface  -  find prior attempts that failed.
26- Logs / telemetry / traces  -  actual failure modes and frequencies.
27- Tests  -  what's currently considered correct.
28- Configuration / feature flags  -  capability already present but unused.
29 
30Cite exact paths and line numbers when you bring evidence to the user.
31 
32## Proactive discovery for software
33 
34Before asking a design or product question, make a small local investigation first. The goal is not exhaustive research; it is to avoid asking the user for facts the repository can already answer.
35 
36Default sequence:
37 
381. Search names and concepts with `rg`.
392. Read the nearest implementation and public API/index files.
403. Check tests for the current behavioral contract.
414. Check recent issues/PRs/docs if the task mentions them.
425. Only then ask the user for intent or trade-off decisions.
43 
44Question shape:
45 
46```
47Evidence: `path/to/file.ts:42` already routes X through Y, and `path/to/test.ts:18` treats Z as required.
48Question: Should the value boundary be "preserve Z while changing Y", or is Z now negotiable?
49Recommended: preserve Z unless the current task explicitly de-scopes it.
50```
51 
52Do not ask:
53 
54- "Where is this implemented?"
55- "Does the app already support this?"
56- "What tests cover this?"
57- "What does production currently do?"
58 
59Inspect those first. Ask only what cannot be inferred: desired outcome, acceptable risk, priority, taste, rollout appetite, or whether a current behavior is intentional.
60 
61## Default creative options for software
62 
63When generating alternatives, deliberately include each of these:
64 
65- **No-build**  -  accept the status-quo with measurement.
66- **Config-only**  -  flip a flag, change a threshold, adjust a quota.
67- **Manual / operational**  -  a human runs the process for two weeks; we measure pain.
68- **Comms-only**  -  change documentation, error message, runbook.
69- **Instrumentation-first**  -  add telemetry; decide later.
70- **Contract-only**  -  change the API/event shape; let consumers adapt.
71- **UI-only**  -  surface the existing capability; no backend change.
72- **Backend-only**  -  fix the data model; UI catches up later.
73- **Lean build**  -  minimum diff that delivers basic function.
74- **Full build**  -  comprehensive solution.
75 
76Drop the ones that obviously don't fit, but force yourself to consider each.
77 
78## Software-specific evaluation criteria
79 
80(See `evaluation-matrix.md` for full template.)
81 
82The criteria most teams under-weight:
83 
84- **Reversibility**  -  config flips beat schema changes beat data migrations beat contract breaks.
85- **Time to feedback**  -  a 1-day option that teaches > a 6-week option that delivers.
86- **Operational burden**  -  a feature that needs a daily human action will rot.
87 
88## ADR template (compact)
89 
90```
91# ADR-NNNN: <title>
92 
93Status: Proposed | Accepted | Superseded by ADR-NNNN
94Date: YYYY-MM-DD
95 
96## Context
97<problem, constraints, evidence (cite paths/links)>
98 
99## Decision
100<chosen option, in 2-4 sentences>
101 
102## Alternatives considered
103- <option B>: rejected because <reason>
104- <option C>: rejected because <reason>
105 
106## Consequences
107- Positive: <what we gain>
108- Negative / accepted risks: <what we lose, with detection signals>
109- Reversal cost: <how to undo>
110```
111 
112## PRD template (compact)
113 
114```
115# <Feature>
116 
117## Outcome (not feature)
118<one measurable sentence>
119 
120## Functions delivered (verb + noun)
121- Basic: ...
122- Secondary: ...
123- Explicitly NOT delivered: ...
124 
125## Users / stakeholders
126<roles, with the one whose buy-in is decisive marked>
127 
128## Acceptance criteria
129- ...
130 
131## Out of scope
132- ...
133 
134## Rollout / rollback
135- Flag, stages, kill switch, on-call playbook entry.
136 
137## Observability
138- Metric, log, alert, dashboard link.
139```
140 
141## Issue slice template
142 
143```
144Title: <verb + noun, basic function level>
145Scope: <single PR-sized, <=2 days>
146Exit criteria: <how reviewer/QA confirms>
147Observability: <what telemetry proves it works in prod>
148Rollback: <flag/revert path>
149Depends on: <issue IDs>
150Risk pointer: <R<n> from register>
151```
152 
153## Review checklist (post-implementation)
154 
155- Every retained component maps to a basic or required function.
156- Every public surface has at least one test.
157- Every new failure mode has a metric or log.
158- Rollback path is documented and rehearsed in writing.
159- Cost surprises (tokens, egress, log volume) are bounded.
160- ADR is updated; PRD is closed; issues link to the ADR.
161