self-evolving-workflow 0.0.0-stage → 0.1.3
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/LICENSE +27 -0
- package/README.md +90 -2
- package/dist/agent-memory-prompts.d.ts +13 -0
- package/dist/agent-memory-prompts.js +55 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +6 -0
- package/dist/closeout.d.ts +105 -0
- package/dist/closeout.js +479 -0
- package/dist/code.d.ts +39 -0
- package/dist/code.js +124 -0
- package/dist/common.d.ts +9 -0
- package/dist/common.js +42 -0
- package/dist/context-envelope.d.ts +59 -0
- package/dist/context-envelope.js +23 -0
- package/dist/host-adapters.d.ts +34 -0
- package/dist/host-adapters.js +151 -0
- package/dist/http.d.ts +3 -0
- package/dist/http.js +90 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +13 -0
- package/dist/knowledge-cli.d.ts +183 -0
- package/dist/knowledge-cli.js +654 -0
- package/dist/knowledge-reads.d.ts +71 -0
- package/dist/knowledge-reads.js +193 -0
- package/dist/memory.d.ts +97 -0
- package/dist/memory.js +250 -0
- package/dist/retrospective.d.ts +57 -0
- package/dist/retrospective.js +248 -0
- package/dist/search.d.ts +36 -0
- package/dist/search.js +112 -0
- package/dist/skill-addition.d.ts +25 -0
- package/dist/skill-addition.js +89 -0
- package/dist/skill-design.d.ts +96 -0
- package/dist/skill-design.js +226 -0
- package/dist/skill-replay.d.ts +55 -0
- package/dist/skill-replay.js +451 -0
- package/dist/skill-route.d.ts +30 -0
- package/dist/skill-route.js +75 -0
- package/dist/transcript-evidence.d.ts +3 -0
- package/dist/transcript-evidence.js +58 -0
- package/dist/upstream/chunker.d.ts +24 -0
- package/dist/upstream/chunker.js +96 -0
- package/dist/upstream/file-protocol.d.ts +45 -0
- package/dist/upstream/file-protocol.js +117 -0
- package/dist/upstream/frontmatter.d.ts +47 -0
- package/dist/upstream/frontmatter.js +86 -0
- package/dist/upstream/graph-search.d.ts +33 -0
- package/dist/upstream/graph-search.js +67 -0
- package/dist/upstream/l1-extraction.d.ts +26 -0
- package/dist/upstream/l1-extraction.js +405 -0
- package/dist/upstream/llm.d.ts +8 -0
- package/dist/upstream/llm.js +1 -0
- package/dist/upstream/merge.d.ts +50 -0
- package/dist/upstream/merge.js +153 -0
- package/dist/upstream/prompts.d.ts +53 -0
- package/dist/upstream/prompts.js +185 -0
- package/dist/upstream/search-utils.d.ts +34 -0
- package/dist/upstream/search-utils.js +55 -0
- package/dist/upstream/slug.d.ts +26 -0
- package/dist/upstream/slug.js +103 -0
- package/dist/upstream/template.d.ts +29 -0
- package/dist/upstream/template.js +80 -0
- package/dist/upstream/tokenize.d.ts +4 -0
- package/dist/upstream/tokenize.js +29 -0
- package/dist/wiki-change.d.ts +76 -0
- package/dist/wiki-change.js +299 -0
- package/dist/wiki-entry.d.ts +26 -0
- package/dist/wiki-entry.js +93 -0
- package/dist/wiki-ingest.d.ts +12 -0
- package/dist/wiki-ingest.js +126 -0
- package/dist/wiki-migration.d.ts +16 -0
- package/dist/wiki-migration.js +268 -0
- package/dist/wiki-tokens.d.ts +1 -0
- package/dist/wiki-tokens.js +46 -0
- package/dist/wiki.d.ts +103 -0
- package/dist/wiki.js +330 -0
- package/dist/workflow-cli.d.ts +2 -0
- package/dist/workflow-cli.js +258 -0
- package/dist/workflow-install.d.ts +36 -0
- package/dist/workflow-install.js +148 -0
- package/dist/workflow-knowledge.d.ts +16 -0
- package/dist/workflow-knowledge.js +24 -0
- package/dist/workflow-mcp.d.ts +2 -0
- package/dist/workflow-mcp.js +144 -0
- package/dist/workflow-names.d.ts +4 -0
- package/dist/workflow-names.js +18 -0
- package/dist/workflow-runtime.d.ts +622 -0
- package/dist/workflow-runtime.js +627 -0
- package/dist/workflow-skills.d.ts +48 -0
- package/dist/workflow-skills.js +141 -0
- package/package.json +76 -4
- package/skills/ew-odyssey/SKILL.md +237 -0
- package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
- package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
- package/skills/ew-odyssey/references/odyssey-base.md +278 -0
- package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
- package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
- package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
- package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
- package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
- package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
- package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
- package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
- package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
- package/skills/ew-odyssey/references/odyssey-review.md +251 -0
- package/skills/ew-odyssey/references/odyssey-security.md +249 -0
- package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
- package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
- package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
- package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
- package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
- package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
- package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
- package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
- package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
- package/skills/ew-orchestrate/SKILL.md +236 -0
- package/skills/ew-orchestrate/references/auto-policy.md +165 -0
- package/skills/ew-orchestrate/references/companion-route.md +52 -0
- package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
- package/skills/ew-orchestrate/references/goal.md +53 -0
- package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
- package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
- package/skills/ew-orchestrate/references/planning.md +137 -0
- package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
- package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
- package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
- package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
- package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
- package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
- package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
- package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
- package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
- package/skills/ew-skill-design/SKILL.md +28 -0
- package/skills/ew-skill-design/references/package-contract.md +28 -0
- package/skills/ew-skill-design/references/validation.md +7 -0
- package/skills/team-swarm/SKILL.md +231 -0
- package/skills/team-swarm/references/mcp-coordination.md +10 -0
- package/skills/team-swarm/roles/analyst/role.md +181 -0
- package/skills/team-swarm/roles/ant/role.md +149 -0
- package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
- package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
- package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
- package/skills/team-swarm/roles/coordinator/role.md +228 -0
- package/skills/team-swarm/roles/scorer/role.md +150 -0
- package/skills/team-swarm/scripts/aco.py +646 -0
- package/skills/team-swarm/scripts/pheromone.py +144 -0
- package/skills/team-swarm/scripts/scoring.py +111 -0
- package/skills/team-swarm/scripts/test_aco.py +606 -0
- package/skills/team-swarm/specs/ant-output-schema.md +127 -0
- package/skills/team-swarm/specs/convergence-criteria.md +108 -0
- package/skills/team-swarm/specs/pheromone-schema.md +125 -0
- package/skills/team-swarm/specs/swarm-config-template.json +71 -0
- package/skills/team-swarm/specs/swarm-protocol.md +123 -0
- package/skills/workflow-closeout/SKILL.md +10 -0
- package/skills/workflow-evolve/SKILL.md +79 -0
- package/skills/workflow-evolve/references/agy-gate.md +27 -0
- package/skills/workflow-evolve/references/auto-loop.md +20 -0
- package/skills/workflow-evolve/references/history-review.md +14 -0
- package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
- package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
- package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
- package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
- package/workflows/index.json +23 -0
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
<!-- session-mode: inherited -->
|
|
2
|
+
|
|
3
|
+
# Workflow: Odyssey UI (Codex)
|
|
4
|
+
|
|
5
|
+
6-dimension visual experience audit — survey design context, audit dimensions, divergent exploration, fix, verify, generalize. Codex-adapted: uses `spawn_agents_on_csv`, `request_user_input`, `update_plan`.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## State Chain
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
S_INTAKE → S_SURVEY → S_AUDIT → S_DIVERGE → S_FIX → S_VERIFY → [back-half]
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Back-half: `S_GENERALIZE → S_DISCOVER → S_RECORD → END` (see [shared Codex phases](odyssey-base-codex.md) §Shared Back-Half).
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Boundary
|
|
20
|
+
|
|
21
|
+
**In scope:** Target component/page visual experience optimization — audit 6 dimensions, divergent exploration, fix, generalize to sibling components.
|
|
22
|
+
**Out of scope:** Backend/data/API → `--mode planex` | Deep bug investigation → `--mode debug` | Code quality review → `--mode review`.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Decision Gate
|
|
27
|
+
|
|
28
|
+
ONLY these qualify as decisions: brand/style direction requiring human creative judgment | layout restructuring that significantly changes user flow | requires new design tokens or breaking component API.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Context
|
|
33
|
+
|
|
34
|
+
### Target Resolution
|
|
35
|
+
|
|
36
|
+
| Input | Resolution |
|
|
37
|
+
|-------|-----------|
|
|
38
|
+
| Component path | Audit component |
|
|
39
|
+
| Page/route | Audit page |
|
|
40
|
+
| `staged` / `HEAD` | Diff UI changes |
|
|
41
|
+
| Feature area | Resolve to components/pages |
|
|
42
|
+
|
|
43
|
+
### Dimensions (6)
|
|
44
|
+
|
|
45
|
+
| Dimension | Focus |
|
|
46
|
+
|-----------|-------|
|
|
47
|
+
| visual_hierarchy | Spacing, typography scale, color contrast, alignment, whitespace, visual weight |
|
|
48
|
+
| interaction_states | Hover, focus, active, disabled, loading, error, empty, selected states |
|
|
49
|
+
| accessibility | WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader |
|
|
50
|
+
| responsiveness | Breakpoints, overflow, touch targets, fluid typography, container queries |
|
|
51
|
+
| micro_interactions | Transitions, animations, feedback indicators, loading states, progress |
|
|
52
|
+
| edge_cases | Long text truncation, empty data, error states, extreme values, i18n, RTL |
|
|
53
|
+
|
|
54
|
+
### Session Fields
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{ "target": "", "dimensions": [],
|
|
58
|
+
"audit_result": { "dimensions_audited": 0, "finding_count": 0, "severity_distribution": {} },
|
|
59
|
+
"diverge_result": { "improvements_proposed": 0, "creative_ideas": 0 },
|
|
60
|
+
"patterns": [], "confirmation": null, "generalization_stats": null }
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### evidence.ndjson Phases
|
|
64
|
+
|
|
65
|
+
`survey|audit|diverge|fix|discovery|decision|self-iteration`
|
|
66
|
+
|
|
67
|
+
### phase_goals[]
|
|
68
|
+
|
|
69
|
+
| ID | Goal | Phase | skip_when |
|
|
70
|
+
|----|------|-------|-----------|
|
|
71
|
+
| G1 | Survey completed | S_SURVEY | — |
|
|
72
|
+
| G2 | Audit completed | S_AUDIT | — |
|
|
73
|
+
| G3 | Divergent exploration done | S_DIVERGE | — |
|
|
74
|
+
| G4 | Zero remaining: all findings/ideas fixed and verified | S_VERIFY | skip_fix |
|
|
75
|
+
| G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
|
|
76
|
+
| G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
|
|
77
|
+
| G7 | Learnings persisted | S_RECORD | — |
|
|
78
|
+
|
|
79
|
+
### understanding.md — 8 Sections
|
|
80
|
+
|
|
81
|
+
1. Target & Design Context
|
|
82
|
+
2. Survey
|
|
83
|
+
3. Audit
|
|
84
|
+
4. Diverge
|
|
85
|
+
5. Verify
|
|
86
|
+
6. Generalize
|
|
87
|
+
7. Discover
|
|
88
|
+
8. Learnings
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## State Machine
|
|
93
|
+
|
|
94
|
+
### Transitions
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
S_SURVEY → S_AUDIT : complete
|
|
98
|
+
S_AUDIT → S_DIVERGE : complete
|
|
99
|
+
S_DIVERGE → S_FIX : !skip_fix AND actionable findings/ideas
|
|
100
|
+
S_DIVERGE → S_GENERALIZE : (skip_fix OR no actionable) AND !skip_generalize
|
|
101
|
+
S_DIVERGE → S_RECORD : (skip_fix OR no actionable) AND skip_generalize
|
|
102
|
+
S_FIX → S_VERIFY : fix implemented
|
|
103
|
+
S_VERIFY → S_GENERALIZE : verified, !skip_generalize
|
|
104
|
+
S_VERIFY → S_RECORD : verified, skip_generalize
|
|
105
|
+
S_VERIFY → S_FIX : needs_rework
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Discover routes: new component to audit → S_AUDIT; fixable sibling → S_FIX.
|
|
109
|
+
|
|
110
|
+
### Actions
|
|
111
|
+
|
|
112
|
+
**A_SURVEY** — (1) Design system inventory: scan for design tokens, CSS variables, theme imports. (2) Current state analysis: styling patterns, layout strategy, component hierarchy. (3) CLI-assisted: `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — survey tokens, spacing, typography, hierarchy, consistency. (4) Evidence phase=survey. Update §2. Mark G1. `update_plan`(G1 → completed)
|
|
113
|
+
|
|
114
|
+
Commit: `"odyssey-ui({slug}): SURVEY — design context survey complete"`
|
|
115
|
+
|
|
116
|
+
**A_AUDIT** — 6-dimension parallel audit via CSV wave.
|
|
117
|
+
|
|
118
|
+
**Step 1 — Generate `ui-audit.csv`:**
|
|
119
|
+
|
|
120
|
+
```csv
|
|
121
|
+
id,dimension,focus,target,status,findings_json,error
|
|
122
|
+
"1","visual_hierarchy","Spacing, typography scale, color contrast, alignment, whitespace, visual weight","{target}","","",""
|
|
123
|
+
"2","interaction_states","Hover, focus, active, disabled, loading, error, empty, selected states","{target}","","",""
|
|
124
|
+
"3","accessibility","WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader","{target}","","",""
|
|
125
|
+
"4","responsiveness","Breakpoints, overflow, touch targets, fluid typography, container queries","{target}","","",""
|
|
126
|
+
"5","micro_interactions","Transitions, animations, feedback indicators, loading states, progress","{target}","","",""
|
|
127
|
+
"6","edge_cases","Long text truncation, empty data, error states, extreme values, i18n, RTL","{target}","","",""
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
If `--dimensions` subset specified, include only matching rows.
|
|
131
|
+
|
|
132
|
+
**Step 2 — Execute CSV wave:**
|
|
133
|
+
|
|
134
|
+
```javascript
|
|
135
|
+
MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
|
|
136
|
+
spawn_agents_on_csv({
|
|
137
|
+
csv_path: `${sessionFolder}/ui-audit.csv`,
|
|
138
|
+
id_column: "id",
|
|
139
|
+
instruction: "You are auditing UI for a specific dimension. Read 'dimension' and 'focus' columns. Scan target component/page files. Return findings as JSON: [{title, severity, file, line, description, suggestion, dimension}].",
|
|
140
|
+
max_concurrency: 6,
|
|
141
|
+
max_runtime_seconds: 3600,
|
|
142
|
+
output_csv_path: `${sessionFolder}/ui-audit-results.csv`,
|
|
143
|
+
output_schema: { id, status, findings_json, error }
|
|
144
|
+
})
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
**Step 3 — Merge:** Collect `findings_json` from all 6 agents. Merge into unified findings list. Evidence phase=audit. Write `audit_result` to session state. Update §3 severity matrix. Mark G2. `update_plan`(G2 → completed)
|
|
148
|
+
|
|
149
|
+
**GATE: all-dimensions-audited** — all 6 dimensions (or `--dimensions` subset) completed with structured findings, merged into severity matrix, evidence phase=audit logged per dimension. Zero dimensions reviewed is BLOCKED (W002 partial from agent failure is a warning).
|
|
150
|
+
|
|
151
|
+
Commit: `"odyssey-ui({slug}): AUDIT — dimension audit complete"`
|
|
152
|
+
|
|
153
|
+
**A_DIVERGE** — Goes beyond defect fixing — "what would make this delightful?"
|
|
154
|
+
|
|
155
|
+
**Step 1 — Generate `diverge.csv`:**
|
|
156
|
+
|
|
157
|
+
```csv
|
|
158
|
+
id,category,focus,target,status,ideas_json,error
|
|
159
|
+
"1","polish","Shadows, borders, transitions, hover, feedback, empty states, skeleton loading, scroll behavior","{target}","","",""
|
|
160
|
+
"2","delight","Motion design, progressive disclosure, smart defaults, contextual hints, celebratory feedback, personality in copy","{target}","","",""
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**Step 2 — Execute CSV wave:**
|
|
164
|
+
|
|
165
|
+
```javascript
|
|
166
|
+
MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
|
|
167
|
+
spawn_agents_on_csv({
|
|
168
|
+
csv_path: `${sessionFolder}/diverge.csv`,
|
|
169
|
+
id_column: "id",
|
|
170
|
+
instruction: "You are exploring UI improvements. Read 'category' (polish or delight) and 'focus' for your area. Go beyond defect fixing — find opportunities. Return ideas as JSON: [{idea, category, impact, effort, description, inspiration}].",
|
|
171
|
+
max_concurrency: 2,
|
|
172
|
+
max_runtime_seconds: 3600,
|
|
173
|
+
output_csv_path: `${sessionFolder}/diverge-results.csv`,
|
|
174
|
+
output_schema: { id, status, ideas_json, error }
|
|
175
|
+
})
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**Step 3 — CLI-assisted:** `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — polish opportunities, micro-interactions, visual rhythm, delight moments.
|
|
179
|
+
|
|
180
|
+
**Step 4 — Consolidate:** Merge audit findings + divergent ideas → prioritized list (severity x impact x effort). Evidence phase=diverge. Update §4. Mark G3. `update_plan`(G3 → completed)
|
|
181
|
+
|
|
182
|
+
**GATE: diverge-explored** — both Polish and Delight agents completed, returning distinct `[{idea, category, impact, effort, description, inspiration}]` entries; CLI-assisted analysis completed; all outputs consolidated with audit findings into a prioritized list (severity × impact × effort); evidence phase=diverge logged; understanding.md §4 written.
|
|
183
|
+
|
|
184
|
+
Commit: `"odyssey-ui({slug}): DIVERGE — divergent exploration complete"`
|
|
185
|
+
|
|
186
|
+
**A_FIX** — Skip if `--skip-fix`. (1) Exhaustive fix: ALL findings/ideas by priority tier (critical → high → medium → low + high-impact ideas). After each tier, re-review — new findings append. (2) Each fix → evidence phase=fix. (3) Normal: `request_user_input` per-fix | `-y`: auto-proceed, record `deferred`.
|
|
187
|
+
|
|
188
|
+
Commit: `"odyssey-ui({slug}): FIX — {tier} tier addressed"`
|
|
189
|
+
|
|
190
|
+
**A_VERIFY** — (1) Run tests (lint, unit, visual regression). (2) `evolve delegate --role review --mode analysis` (`run_in_background: true`) — visual correctness, interaction states, accessibility, responsive. (3) `needs_rework` → S_FIX; `verified` → mark G4. `update_plan`(G4 → completed). Update §5, write `confirmation`.
|
|
191
|
+
|
|
192
|
+
**GATE: zero-remaining-verified** — every prioritized finding and idea is fixed and verified, individually classified (issue / decision), or skipped via `--skip-fix`; tests pass (lint, unit, visual regression); confirmation written; no unaddressed actionable findings; understanding.md §5 updated. `needs_rework` routes back to FIX.
|
|
193
|
+
|
|
194
|
+
Commit: `"odyssey-ui({slug}): VERIFY — fix verification complete"`
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## Generalize Source
|
|
199
|
+
|
|
200
|
+
Audit findings + diverge ideas (severity >= medium OR impact = high).
|
|
201
|
+
|
|
202
|
+
**Discover routing:** new component → S_AUDIT; fixable sibling → S_FIX.
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Knowledge Persistence (§8)
|
|
207
|
+
|
|
208
|
+
Include verified reusable findings in the Run summary and harvest the completed Session through Agent Memory closeout.
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
| Category | Content | Follow-up |
|
|
212
|
+
|----------|---------|-----------|
|
|
213
|
+
| Design pattern | Component pattern + applicable scenarios + token references | `stage spec → ui` |
|
|
214
|
+
| Interaction spec | State definitions + transition rules + feedback patterns | `stage spec → ui` |
|
|
215
|
+
| Accessibility rule | WCAG requirement + implementation approach | `stage spec → ui` |
|
|
216
|
+
| Reusable generalization pattern | Pattern signature + application scope | `stage spec → coding` |
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Completion Summary
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
--- UI ODYSSEY COMPLETE ---
|
|
224
|
+
Target: {target} | Dimensions: {dimensions_audited}
|
|
225
|
+
Findings: {C}C {H}H {M}M {L}L | Diverge: {improvements} polish + {creative} delight
|
|
226
|
+
Fix: {fixed_count} applied, verified={yes|skipped}
|
|
227
|
+
Patterns: {extracted} ({by_layer})
|
|
228
|
+
Scan hits: {total} ({cross_layer} cross-layer)
|
|
229
|
+
Issues: {N} created
|
|
230
|
+
Decisions: {N} resolved, {M} pending, {K} deferred
|
|
231
|
+
Learnings: {N} persisted
|
|
232
|
+
Self-iter: {N} rounds
|
|
233
|
+
Goals: {done}/{total} ({skipped} skipped)
|
|
234
|
+
---
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## Mode `-y` Points
|
|
240
|
+
|
|
241
|
+
| Decision Point | Normal | `-y` |
|
|
242
|
+
|---------------|--------|------|
|
|
243
|
+
| A_FIX confirmation | `request_user_input` | auto-proceed `deferred` |
|
|
244
|
+
| A_DISCOVER routing | `request_user_input` | auto-fix w/ template, issue for rest |
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## Phase Gates
|
|
249
|
+
|
|
250
|
+
- **Discovery gate** (SURVEY): evidence logged, understanding.md updated. Survey requires all scan types attempted.
|
|
251
|
+
- **Audit gate** (AUDIT+DIVERGE): all dimension agents completed, findings merged. Diverge agents completed, ideas consolidated. Zero dimensions reviewed is BLOCKED (W002 partial allowed).
|
|
252
|
+
- **FIX gate:** current priority tier fully addressed. Per-fix evidence logged. Auto-commit per tier.
|
|
253
|
+
- **VERIFY gate:** tests pass; confirmation written, understanding.md updated, verify goal marked. needs_rework → route back to FIX.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Error Codes
|
|
258
|
+
|
|
259
|
+
| Code | Severity | Condition | Recovery |
|
|
260
|
+
|------|----------|-----------|----------|
|
|
261
|
+
| E001 | error | No target provided | Provide target or -c |
|
|
262
|
+
| E002 | error | Target path not found | Check path |
|
|
263
|
+
| W002 | warning | Some dimension agents failed | Partial coverage accepted |
|
|
264
|
+
| W004 | warning | Generalization 0 hits after full 3-layer scan | Advance to S_RECORD |
|
|
265
|
+
| W005 | warning | Pending decisions | Filter evidence phase=decision |
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## Success Criteria
|
|
270
|
+
|
|
271
|
+
- [ ] Target resolved; session + output files created
|
|
272
|
+
- [ ] Survey completed with design system inventory + current state analysis
|
|
273
|
+
- [ ] 6-dimension audit completed with structured findings + severity matrix
|
|
274
|
+
- [ ] Divergent exploration: polish + delight ideas consolidated with audit findings
|
|
275
|
+
- [ ] understanding.md 8 sections written progressively (§1–§8)
|
|
276
|
+
- [ ] Fix + verify (unless --skip-fix); all findings/ideas addressed by priority
|
|
277
|
+
- [ ] Multi-layer generalization + discovery triage (unless --skip-generalize)
|
|
278
|
+
- [ ] phase_goals derived, tracked, and hardened-audited; goal_mode injected via prepare goal:true
|
|
279
|
+
- [ ] Session resumable via -c; completion summary emitted
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Next Step Routing
|
|
284
|
+
|
|
285
|
+
| Condition | Next |
|
|
286
|
+
|-----------|------|
|
|
287
|
+
| Discovery issues created | `Open the follow-up findings in the project issue tracker` |
|
|
288
|
+
| Backend/data issue found | `$ew-odyssey <target> --mode planex` |
|
|
289
|
+
| Deep bug investigation | `$ew-odyssey <target> --mode debug` |
|
|
290
|
+
| Code quality review | `$ew-odyssey <changed-files> --mode review` |
|
|
291
|
+
| Document pattern | Review the component and harvest reusable methods through Agent Memory. |
|
|
292
|
+
| Second opinion | `evolve delegate "<review prompt>" --mode analysis` |
|
|
293
|
+
| Design/interaction pattern to persist | `stage spec → ui` |
|
|
294
|
+
| Pending decisions | Filter evidence phase=decision status=pending |
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-odyssey-ui
|
|
3
|
+
prepare: odyssey-ui
|
|
4
|
+
session-mode: inherited
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Workflow: Odyssey UI
|
|
8
|
+
|
|
9
|
+
6-dimension visual experience audit — survey design context → audit dimensions → divergent exploration → fix → verify → generalize.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## State Chain
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
S_INTAKE → S_SURVEY → S_AUDIT → S_DIVERGE → S_FIX → S_VERIFY → [back-half]
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Back-half: `S_GENERALIZE → S_DISCOVER → S_RECORD → END` (see [shared phases](odyssey-base.md) §Shared Back-Half).
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Boundary
|
|
24
|
+
|
|
25
|
+
**In scope:** Target component/page visual experience optimization — audit 6 dimensions, divergent exploration, fix, generalize to sibling components.
|
|
26
|
+
**Out of scope:** Backend/data/API → `--mode planex` | Deep bug investigation → `--mode debug` | Code quality review → `--mode review`.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Decision Gate
|
|
31
|
+
|
|
32
|
+
ONLY these qualify as decisions: brand/style direction requiring human creative judgment | layout restructuring that significantly changes user flow | requires new design tokens or breaking component API.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Context
|
|
37
|
+
|
|
38
|
+
### Target Resolution
|
|
39
|
+
|
|
40
|
+
| Input | Resolution |
|
|
41
|
+
|-------|-----------|
|
|
42
|
+
| Component path | Audit component |
|
|
43
|
+
| Page/route | Audit page |
|
|
44
|
+
| `staged` / `HEAD` | Diff UI changes |
|
|
45
|
+
| Feature area | Resolve to components/pages |
|
|
46
|
+
|
|
47
|
+
### Dimensions (6)
|
|
48
|
+
|
|
49
|
+
| Dimension | Focus |
|
|
50
|
+
|-----------|-------|
|
|
51
|
+
| visual_hierarchy | Spacing, typography scale, color contrast, alignment, whitespace, visual weight |
|
|
52
|
+
| interaction_states | Hover, focus, active, disabled, loading, error, empty, selected states |
|
|
53
|
+
| accessibility | WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader |
|
|
54
|
+
| responsiveness | Breakpoints, overflow, touch targets, fluid typography, container queries |
|
|
55
|
+
| micro_interactions | Transitions, animations, feedback indicators, loading states, progress |
|
|
56
|
+
| edge_cases | Long text truncation, empty data, error states, extreme values, i18n, RTL |
|
|
57
|
+
|
|
58
|
+
### Session Fields
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{ "target": "", "dimensions": [],
|
|
62
|
+
"audit_result": { "dimensions_audited": 0, "finding_count": 0, "severity_distribution": {} },
|
|
63
|
+
"diverge_result": { "improvements_proposed": 0, "creative_ideas": 0 },
|
|
64
|
+
"patterns": [], "confirmation": null, "generalization_stats": null }
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### evidence.ndjson Phases
|
|
68
|
+
|
|
69
|
+
`survey|audit|diverge|fix|discovery|decision|self-iteration`
|
|
70
|
+
|
|
71
|
+
### phase_goals[]
|
|
72
|
+
|
|
73
|
+
| ID | Goal | Phase | skip_when |
|
|
74
|
+
|----|------|-------|-----------|
|
|
75
|
+
| G1 | Survey completed | S_SURVEY | — |
|
|
76
|
+
| G2 | Audit completed | S_AUDIT | — |
|
|
77
|
+
| G3 | Divergent exploration done | S_DIVERGE | — |
|
|
78
|
+
| G4 | Zero remaining: all findings/ideas fixed and verified | S_VERIFY | skip_fix |
|
|
79
|
+
| G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
|
|
80
|
+
| G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
|
|
81
|
+
| G7 | Learnings persisted | S_RECORD | — |
|
|
82
|
+
|
|
83
|
+
### understanding.md — 8 Sections
|
|
84
|
+
|
|
85
|
+
1. Target & Design Context
|
|
86
|
+
2. Survey
|
|
87
|
+
3. Audit
|
|
88
|
+
4. Diverge
|
|
89
|
+
5. Verify
|
|
90
|
+
6. Generalize
|
|
91
|
+
7. Discover
|
|
92
|
+
8. Learnings
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## State Machine
|
|
97
|
+
|
|
98
|
+
### Transitions
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
S_SURVEY → S_AUDIT : complete
|
|
102
|
+
S_AUDIT → S_DIVERGE : complete
|
|
103
|
+
S_DIVERGE → S_FIX : !skip_fix AND actionable findings/ideas
|
|
104
|
+
S_DIVERGE → S_GENERALIZE : (skip_fix OR no actionable) AND !skip_generalize
|
|
105
|
+
S_DIVERGE → S_RECORD : (skip_fix OR no actionable) AND skip_generalize
|
|
106
|
+
S_FIX → S_VERIFY : fix implemented
|
|
107
|
+
S_VERIFY → S_GENERALIZE : verified, !skip_generalize
|
|
108
|
+
S_VERIFY → S_RECORD : verified, skip_generalize
|
|
109
|
+
S_VERIFY → S_FIX : needs_rework
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Discover routes: new component to audit → S_AUDIT; fixable sibling → S_FIX.
|
|
113
|
+
|
|
114
|
+
### Actions
|
|
115
|
+
|
|
116
|
+
**A_SURVEY** — (1) Design system inventory: scan for design tokens, CSS variables, theme imports. (2) Current state analysis: styling patterns, layout strategy, component hierarchy. (3) CLI-assisted: `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — survey tokens, spacing, typography, hierarchy, consistency. (4) Evidence phase=survey. Update §2. Mark G1.
|
|
117
|
+
|
|
118
|
+
Commit: `"odyssey-ui({slug}): SURVEY — design context survey complete"`
|
|
119
|
+
|
|
120
|
+
**A_AUDIT** — Spawn 6 parallel Agents (one per dimension, or `--dimensions` subset; see Dimensions table). Each returns `[{title, severity, file, line, description, suggestion, dimension}]`. Merge → evidence phase=audit. Write `audit_result`. Update §3 severity matrix. Mark G2.
|
|
121
|
+
|
|
122
|
+
**GATE: all-dimensions-audited** — all 6 dimensions (or `--dimensions` subset) completed with structured findings, merged into severity matrix, evidence phase=audit logged per dimension. Zero dimensions reviewed is BLOCKED (W002 partial from agent failure is a warning).
|
|
123
|
+
|
|
124
|
+
Commit: `"odyssey-ui({slug}): AUDIT — dimension audit complete"`
|
|
125
|
+
|
|
126
|
+
**A_DIVERGE** — Goes beyond defect fixing — "what would make this delightful?"
|
|
127
|
+
|
|
128
|
+
**Step 1 — 2 parallel Agents:**
|
|
129
|
+
- **Polish Agent**: shadows, borders, transitions, hover, feedback, empty states, skeleton loading, scroll behavior.
|
|
130
|
+
- **Delight Agent**: motion design, progressive disclosure, smart defaults, contextual hints, celebratory feedback, personality in copy.
|
|
131
|
+
|
|
132
|
+
Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`.
|
|
133
|
+
|
|
134
|
+
**Step 2 — CLI-assisted:** `evolve delegate --role analyze --mode analysis` (`run_in_background: true`) — polish opportunities, micro-interactions, visual rhythm, delight moments.
|
|
135
|
+
|
|
136
|
+
**Step 3 — Consolidate:** merge audit findings + divergent ideas → prioritized list (severity × impact × effort). Evidence phase=diverge. Update §4. Mark G3.
|
|
137
|
+
|
|
138
|
+
**GATE: diverge-explored** — both Polish and Delight agents completed, returning distinct `[{idea, category, impact, effort, description, inspiration}]` entries; CLI-assisted analysis completed; all outputs consolidated with audit findings into a prioritized list (severity × impact × effort); evidence phase=diverge logged; understanding.md §4 written.
|
|
139
|
+
|
|
140
|
+
Commit: `"odyssey-ui({slug}): DIVERGE — divergent exploration complete"`
|
|
141
|
+
|
|
142
|
+
**A_FIX** — Skip if `--skip-fix`. (1) Exhaustive fix: ALL findings/ideas by priority tier (critical → high → medium → low + high-impact ideas). After each tier, re-review — new findings append. (2) Each fix → evidence phase=fix. (3) Normal: request_user_input per-fix | `-y`: auto-proceed, record `deferred`.
|
|
143
|
+
|
|
144
|
+
Commit: `"odyssey-ui({slug}): FIX — {tier} tier addressed"`
|
|
145
|
+
|
|
146
|
+
**A_VERIFY** — (1) Run tests (lint, unit, visual regression). (2) `evolve delegate --role review --mode analysis` (`run_in_background: true`) — visual correctness, interaction states, accessibility, responsive. (3) `needs_rework` → S_FIX; `verified` → mark G4. Update §5, write `confirmation`.
|
|
147
|
+
|
|
148
|
+
**GATE: zero-remaining-verified** — every prioritized finding and idea is fixed and verified, individually classified (issue / decision), or skipped via `--skip-fix`; tests pass (lint, unit, visual regression); confirmation written; no unaddressed actionable findings; understanding.md §5 updated. `needs_rework` routes back to FIX.
|
|
149
|
+
|
|
150
|
+
Commit: `"odyssey-ui({slug}): VERIFY — fix verification complete"`
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Generalize Source
|
|
155
|
+
|
|
156
|
+
Audit findings + diverge ideas (severity >= medium OR impact = high).
|
|
157
|
+
|
|
158
|
+
**Discover routing:** new component → S_AUDIT; fixable sibling → S_FIX.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Knowledge Persistence (§8)
|
|
163
|
+
|
|
164
|
+
Include verified reusable findings in the Run summary and harvest the completed Session through Agent Memory closeout.
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
| Category | Content | Follow-up |
|
|
168
|
+
|----------|---------|-----------|
|
|
169
|
+
| Design pattern | Component pattern + applicable scenarios + token references | `stage spec → ui` |
|
|
170
|
+
| Interaction spec | State definitions + transition rules + feedback patterns | `stage spec → ui` |
|
|
171
|
+
| Accessibility rule | WCAG requirement + implementation approach | `stage spec → ui` |
|
|
172
|
+
| Reusable generalization pattern | Pattern signature + application scope | `stage spec → coding` |
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## Completion Summary
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
--- UI ODYSSEY COMPLETE ---
|
|
180
|
+
Target: {target} | Dimensions: {dimensions_audited}
|
|
181
|
+
Findings: {C}C {H}H {M}M {L}L | Diverge: {improvements} polish + {creative} delight
|
|
182
|
+
Fix: {fixed_count} applied, verified={yes|skipped}
|
|
183
|
+
Patterns: {extracted} ({by_layer})
|
|
184
|
+
Scan hits: {total} ({cross_layer} cross-layer)
|
|
185
|
+
Issues: {N} created
|
|
186
|
+
Decisions: {N} resolved, {M} pending, {K} deferred
|
|
187
|
+
Learnings: {N} persisted
|
|
188
|
+
Self-iter: {N} rounds
|
|
189
|
+
Goals: {done}/{total} ({skipped} skipped)
|
|
190
|
+
---
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Mode `-y` Points
|
|
196
|
+
|
|
197
|
+
| Decision Point | Normal | `-y` |
|
|
198
|
+
|---------------|--------|------|
|
|
199
|
+
| A_FIX confirmation | request_user_input | auto-proceed `deferred` |
|
|
200
|
+
| A_DISCOVER routing | request_user_input | auto-fix w/ template, issue for rest |
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Phase Gates
|
|
205
|
+
|
|
206
|
+
- **Discovery gate** (SURVEY): evidence logged, understanding.md updated. Survey requires all scan types attempted.
|
|
207
|
+
- **Audit gate** (AUDIT+DIVERGE): all dimension agents completed, findings merged. Diverge agents completed, ideas consolidated. Zero dimensions reviewed is BLOCKED (W002 partial allowed).
|
|
208
|
+
- **FIX gate:** current priority tier fully addressed. Per-fix evidence logged. Auto-commit per tier.
|
|
209
|
+
- **VERIFY gate:** tests pass; confirmation written, understanding.md updated, verify goal marked. needs_rework → route back to FIX.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Error Codes
|
|
214
|
+
|
|
215
|
+
| Code | Severity | Condition | Recovery |
|
|
216
|
+
|------|----------|-----------|----------|
|
|
217
|
+
| E001 | error | No target provided | Provide target or -c |
|
|
218
|
+
| E002 | error | Target path not found | Check path |
|
|
219
|
+
| W002 | warning | Some dimension agents failed | Partial coverage accepted |
|
|
220
|
+
| W004 | warning | Generalization 0 hits after full 3-layer scan | Advance to S_RECORD |
|
|
221
|
+
| W005 | warning | Pending decisions | Filter evidence phase=decision |
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## Success Criteria
|
|
226
|
+
|
|
227
|
+
- [ ] Target resolved; session + output files created
|
|
228
|
+
- [ ] Survey completed with design system inventory + current state analysis
|
|
229
|
+
- [ ] 6-dimension audit completed with structured findings + severity matrix
|
|
230
|
+
- [ ] Divergent exploration: polish + delight ideas consolidated with audit findings
|
|
231
|
+
- [ ] understanding.md 8 sections written progressively (§1–§8)
|
|
232
|
+
- [ ] Fix + verify (unless --skip-fix); all findings/ideas addressed by priority
|
|
233
|
+
- [ ] Multi-layer generalization + discovery triage (unless --skip-generalize)
|
|
234
|
+
- [ ] phase_goals derived, tracked, and hardened-audited; goal_mode injected via prepare goal:true
|
|
235
|
+
- [ ] Session resumable via -c; completion summary emitted
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## Next Step Routing
|
|
240
|
+
|
|
241
|
+
| Condition | Next |
|
|
242
|
+
|-----------|------|
|
|
243
|
+
| Discovery issues created | `Open the follow-up findings in the project issue tracker` |
|
|
244
|
+
| Backend/data issue found | `/ew-odyssey <target> --mode planex` |
|
|
245
|
+
| Deep bug investigation | `/ew-odyssey <target> --mode debug` |
|
|
246
|
+
| Code quality review | `/ew-odyssey <changed-files> --mode review` |
|
|
247
|
+
| Document pattern | Review the component and harvest reusable methods through Agent Memory. |
|
|
248
|
+
| Second opinion | `evolve delegate "<review prompt>" --mode analysis` |
|
|
249
|
+
| Design/interaction pattern to persist | `stage spec → ui` |
|
|
250
|
+
| Pending decisions | Filter evidence phase=decision status=pending |
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-odyssey-debug
|
|
3
|
+
description: "Odyssey debug mode — symptom-driven investigation through archaeology, exploration, hypothesis testing, fix, and confirmation, producing diagnosis with full evidence trail"
|
|
4
|
+
argument-hint: "<issue> [--template performance|memory-leak|race-condition|regression|crash] [--skip-fix] [--skip-generalize] [-y] [-c]"
|
|
5
|
+
contract:
|
|
6
|
+
contract_version: 2.1
|
|
7
|
+
produces:
|
|
8
|
+
- path: outputs/session.json
|
|
9
|
+
kind: session
|
|
10
|
+
schema: session/1.0
|
|
11
|
+
role: primary
|
|
12
|
+
alias: debug-session
|
|
13
|
+
required: true
|
|
14
|
+
- path: outputs/evidence.ndjson
|
|
15
|
+
kind: evidence
|
|
16
|
+
schema: evidence/1.0
|
|
17
|
+
role: evidence
|
|
18
|
+
alias: debug-evidence
|
|
19
|
+
required: true
|
|
20
|
+
- path: outputs/understanding.md
|
|
21
|
+
kind: diagnosis-report
|
|
22
|
+
schema: diagnosis-report/1.0
|
|
23
|
+
role: primary
|
|
24
|
+
alias: debug-understanding
|
|
25
|
+
required: true
|
|
26
|
+
- path: outputs/explore.json
|
|
27
|
+
kind: exploration
|
|
28
|
+
schema: exploration/1.0
|
|
29
|
+
role: evidence
|
|
30
|
+
alias: debug-explore
|
|
31
|
+
required: false
|
|
32
|
+
goal: true
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
# Pre-task Thinking: odyssey-debug
|
|
36
|
+
|
|
37
|
+
## Purpose
|
|
38
|
+
|
|
39
|
+
Odyssey debug is a full-lifecycle debugging cycle: symptom intake → archaeology → code exploration → hypothesis-driven diagnosis → fix → confirmation → generalization → discovery → knowledge persistence. Unlike standalone `/debug` (which produces only a diagnosis), odyssey-debug carries through to fix, confirm, generalize sibling occurrences, and persist learnings.
|
|
40
|
+
|
|
41
|
+
## Input Interpretation
|
|
42
|
+
|
|
43
|
+
Entry modes:
|
|
44
|
+
|
|
45
|
+
| Mode | Trigger | Symptom source |
|
|
46
|
+
|------|---------|----------------|
|
|
47
|
+
| standalone | issue description in `<intent>` | Parse issue description directly |
|
|
48
|
+
| template | `--template <name>` | Apply predefined investigation strategy (performance, memory-leak, race-condition, regression, crash) |
|
|
49
|
+
| continuation | `-c` | Resume via latest session, jump to `current_state` |
|
|
50
|
+
|
|
51
|
+
Template strategies:
|
|
52
|
+
|
|
53
|
+
| Template | Strategy | Use case |
|
|
54
|
+
|----------|----------|----------|
|
|
55
|
+
| `performance` | profiling → hot path → allocation → cache | Performance degradation |
|
|
56
|
+
| `memory-leak` | heap snapshot → retention chain → lifecycle | Memory leaks |
|
|
57
|
+
| `race-condition` | timeline → concurrent access → lock analysis | Race conditions |
|
|
58
|
+
| `regression` | git bisect → diff analysis → boundary check | Regressions |
|
|
59
|
+
| `crash` | stack trace → null chain → error propagation | Crashes / exceptions |
|
|
60
|
+
|
|
61
|
+
## Required Context
|
|
62
|
+
|
|
63
|
+
Context injection (optional, may continue if missing):
|
|
64
|
+
|
|
65
|
+
- Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, ownership
|
|
66
|
+
- Wiki: `agent-memory wiki references "<symptom keywords>" --json` → prior investigations
|
|
67
|
+
- Specs: `agent-memory wiki constraints --category debug --keyword "<symptom>"` → known issues/workarounds
|
|
68
|
+
- Coding specs: `agent-memory wiki constraints --category coding` → patterns relevant to the issue area
|
|
69
|
+
- Role knowledge: `agent-memory wiki references "<topic>" --category debug` → pick relevant items → `agent-memory wiki reference <id>`
|
|
70
|
+
|
|
71
|
+
When prior debug artifacts of the same scope exist, check their root cause first to avoid re-investigating an already-confirmed root cause.
|
|
72
|
+
|
|
73
|
+
## Boundaries and Invariants
|
|
74
|
+
|
|
75
|
+
- **State chain:** `S_INTAKE → S_ARCHAEOLOGY → S_EXPLORE → S_DIAGNOSE → S_FIX → S_CONFIRM → [back-half]`
|
|
76
|
+
- **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
|
|
77
|
+
- **Phase goal tracking** — mark each goal done/failed before transition; no silent skips.
|
|
78
|
+
- **Root cause confirmation requires evidence** — a hypothesis without reproduction or code/log evidence stays "suspected", never promoted to confirmed.
|
|
79
|
+
- **3-strike escalation** — stop after 3 failed hypotheses and escalate (delegate or ask user); do not free-associate a 4th.
|
|
80
|
+
- **Backward trace** from where the error first appears to where correct data turned wrong; fix at the source, not at the symptom.
|
|
81
|
+
- **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
|
|
82
|
+
- **Fix scope:** source code modifications during fix phase are in-scope but MUST be committed per action. Session artifacts target `{run_dir}/outputs/` only.
|
|
83
|
+
- **In scope:** Single bug/issue full loop. **Out of scope:** Features → `--mode planex` | Quality review → `--mode review` | UI → `--mode ui` | Architecture → `/ew-orchestrate --goal plan`.
|
|
84
|
+
|
|
85
|
+
## Run Artifact Metadata
|
|
86
|
+
|
|
87
|
+
Keep domain progress in `outputs/session.json`. Keep the Run identity in the Evolve Session receipt. Resume Debug from the domain checkpoint after attaching to the exact Run.
|
|
88
|
+
|
|
89
|
+
Use the artifact identities in the contract above. For `session.json` and `explore.json`, put `kind`, `schema`, `role` and `alias` in the top-level `_meta` object. Put the same fields in the first JSON record of `evidence.ndjson` under `_meta`, and append later observations as separate lines. Put those fields in the YAML frontmatter of `understanding.md`. Keep the Debug phase fields alongside the artifact metadata. `evolve run complete` validates artifact identities and availability as part of sealing.
|
|
90
|
+
|
|
91
|
+
## Risk Checklist
|
|
92
|
+
|
|
93
|
+
- Is every confirmed root cause backed by a reproduction or code/log evidence? A hypothesis without evidence must stay "suspected", never promoted to confirmed.
|
|
94
|
+
- Did you change only one variable at a time during diagnosis? Simultaneous changes make attribution impossible.
|
|
95
|
+
- Have 3 hypotheses failed? Stop and escalate to architecture inspection — do not propose a 4th hypothesis on your own.
|
|
96
|
+
- Did the trace reach the true source? Fixing at the symptom rather than where correct data first turned wrong leaves the root cause live.
|
|
97
|
+
- Are archaeology/explore results properly logged even on partial failure (W003/W006)? Missing evidence must be flagged, not silently omitted.
|
|
98
|
+
- Is every discovery hit individually classified with a reason? Blanket "pre-existing" skips are forbidden.
|
|
99
|
+
- Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
|
|
100
|
+
|
|
101
|
+
## Gate Intent
|
|
102
|
+
|
|
103
|
+
- `discovery-complete`: archaeology and/or exploration phases have logged evidence, understanding.md §2-§3 are updated, and discovery goal (G2) is marked. Archaeology partial results via W003 are acceptable; explore skip via W006 is acceptable if no CLI tools are available.
|
|
104
|
+
- `diagnosis-confirmed`: all hypotheses are tested with evidence logged (phase=diagnosis), root cause is confirmed with reproduction or code/log evidence (or INCONCLUSIVE after 3-strike escalation), and understanding.md §4-§5 are written. Zero hypotheses tested is BLOCKED.
|
|
105
|
+
- `fix-confirmed`: fix is implemented and tests pass, CLI review completed, `confirmation.overall` is set, understanding.md §6 is written, and verify goal (G3) is marked. `needs_rework` routes back to FIX. Skippable only when `skip_fix == true`.
|