This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 62baef164c89ecdd0009a459d05018c72845d120 Author: Stephen Mallette <[email protected]> AuthorDate: Fri Jul 3 16:35:43 2026 -0400 skills: add DESIGN.md for tinker-review, tinker-dev, tinker-doc Document how each skill is built and how to change it — distinct from the operational guidance in SKILL.md. tinker-review carries real machinery (module map, evidence.json -> report.json data flow, extension points); the guidance skills document their information architecture and where new content goes. Also model tinker-review as two phases (deterministic / agent-driven) and drop an invented "Phase 5" reference. Assisted-by: Claude Code:claude-opus-4-8 --- .skills/tinker-dev/DESIGN.md | 38 ++++++++++++++++++++ .skills/tinker-doc/DESIGN.md | 33 +++++++++++++++++ .skills/tinker-review/DESIGN.md | 78 +++++++++++++++++++++++++++++++++++++++++ .skills/tinker-review/SKILL.md | 2 +- 4 files changed, 150 insertions(+), 1 deletion(-) diff --git a/.skills/tinker-dev/DESIGN.md b/.skills/tinker-dev/DESIGN.md new file mode 100644 index 0000000000..4ad70ab7e3 --- /dev/null +++ b/.skills/tinker-dev/DESIGN.md @@ -0,0 +1,38 @@ +# tinker-dev — Design + +How this skill is structured and how to change it. The development guidance +itself — build recipes, the validation matrix, conventions, beads rules — is the +skill's *content* and lives in `SKILL.md` and `references/`. This document is only +the shape of the artifact and where new content goes. + +## Structure + +A guidance skill, not a program: + +| Path | Role | +|------|------| +| `SKILL.md` | the operational index — the guidance a reader needs up front | +| `references/*.md` | deep, task-specific material, loaded on demand | +| `scripts/check-env.sh` | environment preflight | + +It carries no logic of its own; its effect is what a reader does after reading it. + +## How to change it — where content goes + +Two rules govern the shape, so every change is a routing decision: + +- **Single source of truth — defer, don't duplicate.** General agent rules live + in the root `AGENTS.md`; canonical facts live in the repo (`CONTRIBUTING.md`, + `docs/src/`, `bin/asf-license-header.txt`). New guidance points at its source + and repeats only the TinkerPop-specific thing that is easy to miss. A fact + copied here drifts from its source — so it isn't. +- **Progressive disclosure.** `SKILL.md` stays a lean index; anything deep or + task-specific becomes a `references/` file linked from it, never inlined. + +Applying them: + +- A **general** agent rule → root `AGENTS.md`, not here. +- A **TinkerPop-specific, easy-to-miss** convention → a bullet in `SKILL.md`, + deferring to the canonical file. +- A **new validation rule** → the Definition-of-Done matrix in `SKILL.md`. +- A **new deep topic** → a `references/` file, linked from `SKILL.md`. diff --git a/.skills/tinker-doc/DESIGN.md b/.skills/tinker-doc/DESIGN.md new file mode 100644 index 0000000000..b7fd2d679c --- /dev/null +++ b/.skills/tinker-doc/DESIGN.md @@ -0,0 +1,33 @@ +# tinker-doc — Design + +How this skill is structured and how to change it. The documentation guidance +itself — per-book voice, house style, the executable-block rules — is the skill's +*content* and lives in `SKILL.md` and `references/`. This document is only the +shape of the artifact and where new content goes. + +## Structure + +A guidance skill, not a program: + +| Path | Role | +|------|------| +| `SKILL.md` | the book map, house style, and the load-bearing rules up front | +| `references/*.md` | the voice guide and authoring mechanics, loaded on demand | + +## How to change it — where content goes + +Two rules govern the shape, so every change is a routing decision: + +- **Single source of truth — defer, don't duplicate.** Guidance that overlaps + development (build/validation, changelog discipline) defers to **tinker-dev** + rather than being restated. Canonical documentation lives under `docs/src/`. +- **Progressive disclosure.** `SKILL.md` holds the rule; the details live in a + `references/` file linked from it. + +Applying them: + +- A **new book or audience** → a row in the book map in `SKILL.md`, plus a voice + entry in `references/books-and-voice.md`. +- A **new authoring mechanic** → `references/executable-blocks.md` or + `references/asciidoc-and-wiring.md`; keep `SKILL.md` to the rule, not the how. +- A **new house-style rule** → the House style list in `SKILL.md`. diff --git a/.skills/tinker-review/DESIGN.md b/.skills/tinker-review/DESIGN.md new file mode 100644 index 0000000000..de4cde0700 --- /dev/null +++ b/.skills/tinker-review/DESIGN.md @@ -0,0 +1,78 @@ +# tinker-review — Design + +How the skill is built and how to change it. What a review *does* and the +guidance it applies live in `SKILL.md`, the playbooks, and `references/`. This +document is only the machinery and its extension points. + +## How it works + +The pipeline is two phases, split by what is mechanical and what needs judgment. + +**Phase 1 — deterministic** (`scripts/review.js`) builds the graph and writes +`evidence.json`: fetch PR → worktree → start Gremlin Server → tree-sitter +extract → populate → discover discussions → run the structural checks. It exits +cleanly (a `PHASE1_COMPLETE` sentinel) so a caller can detect completion; the +Gremlin Server container stays up. + +**Phase 2 — agent-driven** does everything that needs judgment: enrich the graph +via the enrichment CLI, an optional functional test, then the report. It ends by +tearing down the container and worktree. + +Data flows one direction through three artifacts: + +``` +source → [Phase 1] → evidence.json → [agent adds narrative] → report.json → [renderer] → HTML +``` + +The knowledge graph is a live **Gremlin Server (TinkerGraph)** — the skill +dogfoods TinkerPop. Phase 1 talks to it directly; Phase 2 opens a fresh +connection per enrichment CLI call, because the process that populated the graph +has already exited. + +### Module map + +| Path | Role | +|------|------| +| `scripts/review.js` | Phase 1 orchestrator — `setup` / `phase1` / `teardown` | +| `scripts/extraction/tree-sitter.js` | source → structural extraction | +| `scripts/graph/*.js` | populate the graph; `confidence.js` / `externals.js` hold the data-model vocabularies | +| `scripts/patterns/*.js` | one structural check per file; each defines its own result `@typedef` | +| `scripts/enrichment/{api,cli}.js` | Phase 2 read/write commands over the live graph | +| `scripts/renderer/{render.js,template.html}` | `report.json` → HTML | +| `playbooks/*.md` | domain review guidance — prompt scaffolds, not code | +| `references/{schema,interfaces}.md` | the graph schema and the evidence composite | + +## Constraints that bound a change + +- **One source of truth per fact.** Each check's result shape is a `@typedef` in + the pattern file that produces it; `references/interfaces.md` holds only the + composite `Evidence` / `ReportPackage` and points at those typedefs. The graph + schema lives once in `references/schema.md`. Never re-declare a shape in a + second place. +- **Type docs carry meaning.** A `@typedef` field gets a prose line saying what + it means and how to weigh it, not just its type — that is what the Interpret + sections and the reviewer consume. +- **Plain JS + JSDoc, no build step.** The skill runs under `node` directly. + Don't add TypeScript, a bundler, or a compile step. +- **Edges obey the data model.** Every edge carries a `confidence` + (`EXTRACTED | INFERRED | AMBIGUOUS`); an edge whose endpoint may fall outside + the changed set is created find-or-create against a marker vertex so it can't + silently vanish. A new edge must follow both. +- **Mechanical vs judgment decides where code goes.** Anything reproducible is a + Phase-1 module; anything needing judgment is a Phase-2 command the agent drives + from a playbook. That boundary tells you where a new capability belongs. + +## How to change it + +- **Add a structural check** — new `scripts/patterns/<name>.js` exporting the + function and its result `@typedef`; call it in `review.js` Phase 1 and add it + to `evidence.checks`; add the type to `Evidence` in `interfaces.md`; reference + it from the relevant playbook's Interpret. +- **Add an enrichment command** — a function in `scripts/enrichment/api.js` (or a + pattern module), wired into `cli.js` (COMMANDS + help + switch), documented in + `SKILL.md`. Edge-creating commands take a `confidence`, default `INFERRED`. +- **Add a playbook** — four sections (Context / Enrich / Interpret / Escape); + Enrich uses real commands, Interpret cites `evidence.json` fields; add a + routing rule in `SKILL.md`. +- **Add an edge or vertex type** — document it in `references/schema.md`; tag new + edges with `confidence`; use find-or-create for cross-boundary endpoints. diff --git a/.skills/tinker-review/SKILL.md b/.skills/tinker-review/SKILL.md index b4291613d8..8e0e808af1 100644 --- a/.skills/tinker-review/SKILL.md +++ b/.skills/tinker-review/SKILL.md @@ -71,7 +71,7 @@ a phase of this run — this is the contract for what to do with the content: |---------|------|---------------------| | **Context** | framing | Orient to the change type and its risks; not actioned directly. | | **Enrich** | Phase 2 | Execute the listed steps using the enrichment CLI commands. | -| **Interpret** | Phase 5 | When writing the report, weigh the named `evidence.json` fields into `findings` / `openQuestions`. | +| **Interpret** | Phase 2 (report) | When writing the report, weigh the named `evidence.json` fields into `findings` / `openQuestions`. | | **Escape** | any phase | Check the stop/escalate conditions; halt or flag when one holds. | Phase 1 already computes every structural check — completeness, coverageGaps,
