|
| 1 | +# `.i-walkthroughs/` schema (v1) |
| 2 | + |
| 3 | +> **Skill template.** This is the canonical copy the `interactive-walkthrough` skill carries. |
| 4 | +> On first use in a repo that has no `.i-walkthroughs/`, copy this file to |
| 5 | +> `<repo>/.i-walkthroughs/schema.md` (then create `README.md`, an empty `index.jsonl`, |
| 6 | +> `entries/`, and `evidence/`) and commit, so the Runlog gate's "per `.i-walkthroughs/schema.md`" |
| 7 | +> always resolves against a repo-local source of truth. |
| 8 | +
|
| 9 | +Canonical field dictionary for walkthrough runlog entries. A future repo-wide RAG ingester |
| 10 | +reads THIS file. Stable contract: glob `**/.i-walkthroughs/entries/*.md`, parse YAML |
| 11 | +frontmatter as the metadata record, treat each `##` body heading as a chunk boundary, upsert |
| 12 | +keyed on `id` (== filename stem), gate migrations on `schema_version`. |
| 13 | + |
| 14 | +## Folder layout |
| 15 | + |
| 16 | +``` |
| 17 | +.i-walkthroughs/ |
| 18 | + README.md # what this is + RAG-forward note |
| 19 | + schema.md # THIS file — single source of truth |
| 20 | + index.jsonl # append-only machine index, one JSON object per entry |
| 21 | + entries/ |
| 22 | + <id>.md # one self-contained learning unit per file |
| 23 | + evidence/ |
| 24 | + <id>/ # per-entry assets (id == entry id) |
| 25 | + before-<vp>.png # pre-fix VIEWPORT screenshot |
| 26 | + after-<vp>.png # post-fix (second-check) VIEWPORT screenshot |
| 27 | + dom-measure.json # {"before":{...},"after":{...}} authoritative numbers |
| 28 | +``` |
| 29 | + |
| 30 | +**File strategy:** one file per `(screen, issue)` learning unit (NOT an append-to-one-log), |
| 31 | +because a RAG hit must return a complete, single-issue document with correct metadata so |
| 32 | +filters like `verdict:resolved AND severity:P1` select exactly the right unit. `index.jsonl` |
| 33 | +is the fast non-vector path to enumerate/pre-filter the corpus without parsing markdown. |
| 34 | + |
| 35 | +**`<id>` == filename stem == frontmatter `id` == `index.jsonl` row key.** Never reused, never changed. |
| 36 | + |
| 37 | +## Slug / id rules |
| 38 | + |
| 39 | +`<id>` = `<YYYY-MM-DD>-<route-slug>-<issue-slug>` |
| 40 | +- `route-slug`: route with `/` → `-`, leading `-` stripped; root `/` → `root`. |
| 41 | +- `issue-slug`: 2–4 word kebab summary of the defect. |
| 42 | +- lowercase ASCII, no spaces. Same-day collision → append `-2`, `-3`. |
| 43 | + |
| 44 | +## Frontmatter fields |
| 45 | + |
| 46 | +| key | type | purpose | |
| 47 | +|---|---|---| |
| 48 | +| `id` | string (== filename stem) | Primary key for RAG upsert/dedup + `index.jsonl` join + git anchor. Immutable. | |
| 49 | +| `schema_version` | int (start 1) | Migration gate for field renames. | |
| 50 | +| `repo` | string `owner/name` | Repo-wide RAG filter dimension (this repo's `owner/name`, e.g. `anombyte93/atlas-ai-website`). | |
| 51 | +| `branch` | string | Branch the fix landed on. | |
| 52 | +| `commit` | git SHA \| `pending` | Hard link to the resolving diff; `pending` until committed. | |
| 53 | +| `date` | ISO date `YYYY-MM-DD` | Day the second check passed; filename prefix + index sort key. | |
| 54 | +| `route` | string app route | Primary filter: "everything learned about `/calculator`". Leading slash; root `/`. | |
| 55 | +| `screen_purpose` | string (one sentence) | The screen soul purpose; anchors the embedding to intended behavior. | |
| 56 | +| `mode` | enum `interactive` \| `auto` \| `mobile` | Which walkthrough mode produced this. | |
| 57 | +| `viewport` | string `WxH` or `WxH@dpr` | Reproduction context (e.g. `390x844`). | |
| 58 | +| `device_class` | enum `mobile` \| `tablet` \| `desktop` | Coarse class for filtering + regression arm. | |
| 59 | +| `severity` | enum `P0` \| `P1` \| `P2` \| `P3` | Reuses `reference/auto-report-schema.md` labels verbatim. | |
| 60 | +| `category` | enum `layout` \| `copy` \| `a11y` \| `perf` \| `security` \| `interaction` \| `data` \| `trust` \| `role-boundary` | Defect taxonomy for clustering. | |
| 61 | +| `root_cause` | string (one line) | The why (NOT the symptom). High-value learn-from-mistakes field. | |
| 62 | +| `assumption_trap` | string \| null | The false belief made/nearly made (e.g. "desktop pass == mobile pass"). Drives `reusable_rule`. | |
| 63 | +| `reusable_rule` | string (one line, imperative) | Portable rule a future agent applies to avoid repeating this. Highest-signal retrieval target. | |
| 64 | +| `evidence_method` | list[enum `dom-measure` \| `viewport-screenshot` \| `console` \| `network` \| `axe` \| `lighthouse` \| `code`] | How proof was gathered, ordered by authority (`dom-measure` first). | |
| 65 | +| `files_changed` | list[string] repo-relative | Source files the fix touched. | |
| 66 | +| `first_check` | object `{result: fail\|pass, metric, evidence_ref}` | Pre-fix proof the issue was real. Required for P0/P1. | |
| 67 | +| `second_check` | object `{result: pass\|fail, metric, evidence_ref, regression_scan: pass\|fail}` | MANDATORY post-fix re-verification. `result=pass` ONLY if same metric now passes AND `regression_scan=pass`. `metric` must be the SAME numeric assertion as `first_check.metric`. | |
| 68 | +| `regression_checks` | list[string] | The specific adjacent things re-verified (other viewport class, overflow, focus, console/CSP). Backs `second_check.regression_scan`. | |
| 69 | +| `verdict` | enum `resolved` \| `partial` \| `regressed` \| `reverted` | Headline outcome. `resolved`=gone + no regression; `partial`=residual remains; `regressed`=fix broke something; `reverted`=rolled back. | |
| 70 | +| `status` | enum `open` \| `verified` \| `shipped` | Lifecycle, orthogonal to verdict. `open`=no passing second check yet; `verified`=second check passed; `shipped`=committed/merged. | |
| 71 | +| `approval` | string \| `pending` | Who approved the mutating action (owner handle + when + channel). In `--mobile` this is the Discord reply. | |
| 72 | +| `evidence_dir` | string repo-relative | `evidence/<id>/` — keeps binaries out of embedded text but linkable. | |
| 73 | +| `tags` | list[string] kebab | Free-form RAG facets beyond the fixed enums. | |
| 74 | +| `related` | list[string] entry ids | Graph edges (recurrence → prior resolved entry, supersedes, caused-by). | |
| 75 | +| `title` | string (short headline) | Display + embedding-friendly summary; also `index.jsonl` `title`. | |
| 76 | + |
| 77 | +## Body sections (in order; each `##` is a chunk boundary) |
| 78 | + |
| 79 | +1. **Lesson (TL;DR)** — standalone 2–4 sentences; restates `root_cause` + `reusable_rule` in prose. Lead chunk. |
| 80 | +2. **Screen & Purpose** — route, role/context, viewport, soul purpose. |
| 81 | +3. **Issue (first check)** — observable QUANTITATIVE symptom; DOM numbers first, then screenshot ref. Never an opinion. |
| 82 | +4. **Root Cause** — underlying cause + the `assumption_trap` narrative. |
| 83 | +5. **Fix** — smallest coherent change, `files_changed`, load-bearing snippet, commit. |
| 84 | +6. **Second Check (re-verification, MANDATORY)** — fresh same-screen/same-viewport evidence: (a) same-defect proof via the same metric, (b) explicit regression scan, then the verdict. |
| 85 | +7. **Reusable Rule** — the portable rule, imperative. |
| 86 | +8. **Decision Trail** — owner decision + channel, rejected alternatives, deferred items, open questions. |
| 87 | +9. **Revisions** — append-only log of in-turn updates (e.g. a regressed second check → re-fix). Keeps the full mistake arc in one unit. |
| 88 | + |
| 89 | +## Re-touch rule |
| 90 | + |
| 91 | +- In-turn correction (a fix regresses on its own second check this turn) → **update the same entry** (Revisions section; verdict flips). |
| 92 | +- A separate later walkthrough re-touching the same screen → **new dated entry** with `related` linking back. The corpus accumulates `mistake → fix → second-check` triples over time. |
| 93 | + |
| 94 | +## `index.jsonl` row shape |
| 95 | + |
| 96 | +One JSON object per line, append-only (never rewrite prior lines): |
| 97 | + |
| 98 | +```json |
| 99 | +{"id":"...","repo":"owner/name","branch":"...","route":"/...","date":"YYYY-MM-DD","severity":"P0|P1|P2|P3","category":"...","verdict":"resolved|partial|regressed|reverted","status":"open|verified|shipped","title":"...","file":"entries/<id>.md"} |
| 100 | +``` |
0 commit comments