TML-2549 drive-domain-model: consolidated Drive units, dispatch discipline, and skill restructure proposal#522
Merged
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds/renames Drive workflow and atomic skills, seeds project-context READMEs/templates and calibration, formalizes per-dispatch build/health/retro/close-out flows, splits spec/plan scopes, updates PR/review conventions, and provisions reconcile/update helpers and trial findings scaffolds. ChangesDrive skill system and documentation reshape
Sequence Diagram(s)sequenceDiagram
participant Start as drive-start-workflow
participant Triage as drive-triage-work
participant Plan as drive-plan-slice
participant Build as drive-build-workflow
participant Health as drive-check-health
participant Retro as drive-run-retro
Start->>Triage: route entry or scope-shift
Triage-->>Start: verdict + setup chain
Start->>Plan: compose slice → dispatch briefs
Plan-->>Build: dispatch-id + brief
loop per dispatch
Build->>Build: pre-flight DoR, delegate implement
Build->>Build: WIP inspect, reviewer findings
Build->>Build: post-flight DoD + intent validation
end
Build-->>Health: trigger post-merge rollup
Health-->>Retro: fire retro if drift/trigger
Retro-->>Drive: land lessons to canonical or project-context
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (2)
.agents/skills/drive-create-project/SKILL.md (1)
123-123: 💤 Low valueClarify timing requirement for Linear Project creation.
The phrasing "created or about to be created as part of this skill's setup" is slightly ambiguous about whether the Linear Project must exist before DoR passes or whether creating it during this skill's execution satisfies the DoR requirement.
Consider clarifying whether: (a) the project must already exist, or (b) the skill creates it as part of setup before proceeding, or (c) either is acceptable.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/drive-create-project/SKILL.md at line 123, Update the checklist item that currently reads "- [ ] **Linear Project** (or comparable tracker) — created or about to be created as part of this skill's setup; assigned to the operator." to explicitly state the timing requirement: indicate whether the Linear Project must exist before DoR, whether the skill will create it during setup before proceeding, or whether either option is acceptable; e.g., change the text around the "**Linear Project**" checklist entry to one clear sentence specifying the chosen policy (must exist prior / created during setup / either) and, if created during setup, note which function or step in the skill (the setup routine referenced in this SKILL.md) performs the creation so reviewers can find the implementation..agents/skills/drive-create-plan/SKILL.md (1)
67-67: 💤 Low valueConsider updating deprecated skill reference in reference material.
Line 67 references
drive-create-spec, which is also deprecated. While this file is marked as reference material, the reference could be updated to suggest readers usedrive-specify-projectinstead, or at minimum note thatdrive-create-specis also deprecated.This would help prevent readers of the reference material from following deprecated paths.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/drive-create-plan/SKILL.md at line 67, Update the deprecated reference to drive-create-spec in the SKILL.md text: replace the suggestion to hand off to `drive-create-spec` with a recommendation to use `drive-specify-project` (or at minimum add a clear note that `drive-create-spec` is deprecated); keep the existing examples of default output paths (`projects/{project}/spec.md` and `projects/{project}/specs/{name}.spec.md`) intact so readers still see where specs land.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/drive-build-workflow/SKILL.md:
- Line 8: The description contains a circular reference ("Renamed and augmented
from `drive-build-workflow`") — update the text in
.agents/skills/drive-build-workflow/SKILL.md so it refers to the correct
original skill `drive-orchestrate-plan` (the metadata field renamed_from:
drive-orchestrate-plan and the note at line ~20 indicate the intended source);
locate the description sentence that currently mentions `drive-build-workflow`
and replace that identifier with `drive-orchestrate-plan` so the
README/description is accurate.
In @.agents/skills/drive-check-health/SKILL.md:
- Around line 122-127: The doc claims the skill is "atomic" and "does one thing:
produces a rollup" but also describes auto-invoking downstream skills (e.g.,
drive-build-workflow, drive-start-workflow, drive-run-retro) in unattended mode;
update SKILL.md to make these behaviors consistent by either (A) stating
explicitly that the skill only emits recommendations/rollups and never
auto-executes downstream actions (adjust the Step 5 bullets to use "recommend" /
"log for operator" only and remove phrases like "proceed to
drive-build-workflow"), or (B) changing the atomic-skill description to allow
automatic downstream firing in unattended mode (add a sentence clarifying that
in unattended mode the skill may invoke downstream skills such as
drive-build-workflow when operator policy permits). Ensure you update the
phrases "atomic skill — does one thing: produces a rollup" and the Step 5 bullet
about "in unattended mode, log and proceed to drive-build-workflow" so they no
longer contradict each other.
In @.agents/skills/drive-create-project/SKILL.md:
- Line 7: Replace the incorrect skill name string "drive-project-specify" with
the correct "drive-specify-project" in the SKILL.md content (the occurrence that
conflicts with the pattern used at line 140 and the rest of the skill
structure); search for the token "drive-project-specify" and update it to
"drive-specify-project" wherever referenced so the skill name follows the
action-before-scope pattern and matches the existing skill structure.
In @.agents/skills/drive-start-workflow/SKILL.md:
- Around line 32-41: Update the ASCII diagram to use the correct skill names:
replace every occurrence of drive-slice-specify with drive-specify-slice,
replace drive-project-specify with drive-specify-project, and replace
drive-project-plan with drive-plan-project so the diagram matches the rest of
the document and referenced skills (drive-specify-slice, drive-specify-project,
drive-plan-project).
In `@drive/README.md`:
- Line 5: The README in drive/ references transient docs under projects/
(protocol-as-memory.md and gradual-ai-adoption.md); remove those links and
either move those markdown files into a durable location (e.g.,
docs/protocol-as-memory.md and docs/gradual-ai-adoption.md) or inline their
essential concepts into drive/README.md, then update the links in
drive/README.md to point to the new docs/ locations (or remove the links if
inlined); ensure any other occurrences noted (lines 10 and 28) are similarly
updated to avoid referencing projects/.
---
Nitpick comments:
In @.agents/skills/drive-create-plan/SKILL.md:
- Line 67: Update the deprecated reference to drive-create-spec in the SKILL.md
text: replace the suggestion to hand off to `drive-create-spec` with a
recommendation to use `drive-specify-project` (or at minimum add a clear note
that `drive-create-spec` is deprecated); keep the existing examples of default
output paths (`projects/{project}/spec.md` and
`projects/{project}/specs/{name}.spec.md`) intact so readers still see where
specs land.
In @.agents/skills/drive-create-project/SKILL.md:
- Line 123: Update the checklist item that currently reads "- [ ] **Linear
Project** (or comparable tracker) — created or about to be created as part of
this skill's setup; assigned to the operator." to explicitly state the timing
requirement: indicate whether the Linear Project must exist before DoR, whether
the skill will create it during setup before proceeding, or whether either
option is acceptable; e.g., change the text around the "**Linear Project**"
checklist entry to one clear sentence specifying the chosen policy (must exist
prior / created during setup / either) and, if created during setup, note which
function or step in the skill (the setup routine referenced in this SKILL.md)
performs the creation so reviewers can find the implementation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 526487a3-d4ba-474b-9f56-a87bda4cfff1
⛔ Files ignored due to path filters (18)
projects/drive-domain-model/README.mdis excluded by!projects/**projects/drive-domain-model/calibration/prisma-next.mdis excluded by!projects/**projects/drive-domain-model/design-decisions.mdis excluded by!projects/**projects/drive-domain-model/model.mdis excluded by!projects/**projects/drive-domain-model/plan.mdis excluded by!projects/**projects/drive-domain-model/principles/brief-discipline.mdis excluded by!projects/**projects/drive-domain-model/principles/decomposition-and-cost.mdis excluded by!projects/**projects/drive-domain-model/principles/definition-of-done.mdis excluded by!projects/**projects/drive-domain-model/principles/definition-of-ready.mdis excluded by!projects/**projects/drive-domain-model/principles/gradual-ai-adoption.mdis excluded by!projects/**projects/drive-domain-model/principles/protocol-as-memory.mdis excluded by!projects/**projects/drive-domain-model/principles/retro.mdis excluded by!projects/**projects/drive-domain-model/principles/roles-and-personas.mdis excluded by!projects/**projects/drive-domain-model/principles/spikes.mdis excluded by!projects/**projects/drive-domain-model/problem-statement.mdis excluded by!projects/**projects/drive-domain-model/skill-restructure.mdis excluded by!projects/**projects/drive-domain-model/spec.mdis excluded by!projects/**projects/drive-domain-model/workflow.mdis excluded by!projects/**
📒 Files selected for processing (32)
.agents/skills/drive-build-workflow/SKILL.md.agents/skills/drive-build-workflow/agents/implementer.md.agents/skills/drive-build-workflow/agents/reviewer.md.agents/skills/drive-build-workflow/templates/code-review.template.md.agents/skills/drive-build-workflow/templates/delegate-implement.md.agents/skills/drive-build-workflow/templates/delegate-review.md.agents/skills/drive-build-workflow/templates/unattended-decisions.template.md.agents/skills/drive-check-health/SKILL.md.agents/skills/drive-code-review/SKILL.md.agents/skills/drive-create-plan/SKILL.md.agents/skills/drive-create-project/SKILL.md.agents/skills/drive-create-spec/SKILL.md.agents/skills/drive-deliver-workflow/SKILL.md.agents/skills/drive-discussion/SKILL.md.agents/skills/drive-plan-project/SKILL.md.agents/skills/drive-plan-slice/SKILL.md.agents/skills/drive-pr-description/SKILL.md.agents/skills/drive-pr-local-review/SKILL.md.agents/skills/drive-run-retro/SKILL.md.agents/skills/drive-specify-project/SKILL.md.agents/skills/drive-specify-slice/SKILL.md.agents/skills/drive-start-workflow/SKILL.md.agents/skills/drive-triage-work/SKILL.md.gitignoredrive/README.mddrive/health/README.mddrive/plan/README.mddrive/pr/README.mddrive/project/README.mddrive/retro/README.mddrive/spec/README.mddrive/triage/README.md
wmadden
force-pushed
the
tml-2549-agile-agent-orchestration
branch
from
24017b2 to
fa03911
Compare
@prisma-next/extension-author-tools
@prisma-next/mongo-runtime
@prisma-next/family-mongo
@prisma-next/sql-runtime
@prisma-next/family-sql
@prisma-next/extension-arktype-json
@prisma-next/extension-cipherstash
@prisma-next/middleware-cache
@prisma-next/mongo
@prisma-next/extension-paradedb
@prisma-next/extension-pgvector
@prisma-next/extension-postgis
@prisma-next/postgres
@prisma-next/sql-orm-client
@prisma-next/sqlite
@prisma-next/target-mongo
@prisma-next/adapter-mongo
@prisma-next/driver-mongo
@prisma-next/contract
@prisma-next/utils
@prisma-next/config
@prisma-next/errors
@prisma-next/framework-components
@prisma-next/operations
@prisma-next/ts-render
@prisma-next/contract-authoring
@prisma-next/ids
@prisma-next/psl-parser
@prisma-next/psl-printer
@prisma-next/cli
@prisma-next/emitter
@prisma-next/migration-tools
prisma-next
@prisma-next/vite-plugin-contract-emit
@prisma-next/mongo-codec
@prisma-next/mongo-contract
@prisma-next/mongo-value
@prisma-next/mongo-contract-psl
@prisma-next/mongo-contract-ts
@prisma-next/mongo-emitter
@prisma-next/mongo-schema-ir
@prisma-next/mongo-query-ast
@prisma-next/mongo-orm
@prisma-next/mongo-query-builder
@prisma-next/mongo-lowering
@prisma-next/mongo-wire
@prisma-next/sql-contract
@prisma-next/sql-errors
@prisma-next/sql-operations
@prisma-next/sql-schema-ir
@prisma-next/sql-contract-psl
@prisma-next/sql-contract-ts
@prisma-next/sql-contract-emitter
@prisma-next/sql-lane-query-builder
@prisma-next/sql-relational-core
@prisma-next/sql-builder
@prisma-next/target-postgres
@prisma-next/target-sqlite
@prisma-next/adapter-postgres
@prisma-next/adapter-sqlite
@prisma-next/driver-postgres
@prisma-next/driver-sqlite
commit: |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 16
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
skills-contrib/drive-build-workflow/SKILL.md (2)
43-49:⚠️ Potential issue | 🟠 Major | ⚡ Quick winUpdate legacy skill references to the split spec/plan skills.
Line 43, Line 48, Line 168, Line 193, and Line 736-738 still route through
drive-create-spec/drive-create-plan, which conflicts with this PR’s split todrive-specify-*anddrive-plan-*. This creates incorrect handoff guidance in the orchestration contract.Also applies to: 167-169, 193-194, 736-738
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills-contrib/drive-build-workflow/SKILL.md` around lines 43 - 49, Search the SKILL.md for all occurrences of the legacy skill names "drive-create-spec" and "drive-create-plan" (they appear in the "Do not use this skill for" section and elsewhere) and replace them with the new split skill families "drive-specify-*" for spec-related handoffs and "drive-plan-*" for plan-related handoffs; update the surrounding guidance so the orchestration contract explicitly routes spec work to drive-specify-* and plan work to drive-plan-*, and ensure every mention in the file (including the earlier bullet points and any guidance lines that currently reference drive-create-spec/drive-create-plan) is updated to the new names so the handoff guidance is consistent.
205-215:⚠️ Potential issue | 🟠 Major | ⚡ Quick winSubcommand argument naming is inconsistent with dispatch semantics.
Line 205-207 and Line 214 still advertise
[milestone-id], while the protocol now frames iterations per dispatch (and Line 529 already usesiterate <dispatch-id>). Keep one canonical argument name to avoid incorrect operator invocation.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills-contrib/drive-build-workflow/SKILL.md` around lines 205 - 215, The README shows inconsistent subcommand argument names: change the documented usage of the three subcommands "/drive-build-workflow iterate [milestone-id]", "/drive-build-workflow implement [milestone-id]", and "/drive-build-workflow review" to use the canonical dispatch identifier used by the protocol (e.g. "/drive-build-workflow iterate <dispatch-id>", "/drive-build-workflow implement <dispatch-id>", "/drive-build-workflow review <dispatch-id>") so all examples and the explanatory text refer to "<dispatch-id>" (or the single canonical token used elsewhere like "dispatch-id") instead of "[milestone-id]"; update the brief descriptions for the iterate/implement/review lines and the example and any parenthetical note that mentions mapping to plan.md to reference dispatch IDs consistently (look for the command strings iterate/implement/review and the parenthetical mapping to plan.md to make the replacements).skills-contrib/drive-discussion/SKILL.md (1)
157-157:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWorked example uses deprecated handoff skill.
This line still routes to
drive-create-spec; it should reference the scoped split (drive-specify-projectordrive-specify-slice) to match the rest of this PR’s workflow contract.As per coding guidelines, "
**/*.md: Keep docs current (READMEs, rules, links)."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills-contrib/drive-discussion/SKILL.md` at line 157, Update the docs to stop referencing the deprecated handoff skill `drive-create-spec`; change the Outcome line to point to the new scoped split handoff (e.g., `drive-specify-project` or `drive-specify-slice`) so it matches the rest of the PR workflow contract and README guidance; ensure the wording and target path (`projects/<project>/spec.md`) remain correct but route to the appropriate new skill name used elsewhere in this PR.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills-contrib/drive-build-workflow/SKILL.md`:
- Around line 58-59: Replace transient /projects/ links in SKILL.md with durable
documentation targets: find the link
`/projects/drive-domain-model/principles/definition-of-ready.md` (and the other
occurrences noted around lines 72-73, 133-134, 210-213) and update each href to
point to the permanent docs/ location or the package README that holds the same
content; if the durable doc does not yet exist, create or move the content into
docs/ or the appropriate README and then update the link, ensuring relative
paths resolve and link text remains descriptive.
In `@skills-contrib/drive-check-health/SKILL.md`:
- Line 28: Replace the transient projects/ link in SKILL.md (the reference to
projects/drive-domain-model/workflow.md found in the phrase "Three canonical
cadences") with a durable docs or package README target; update any other
occurrences mentioned (lines referenced around 194-196) to point at the stable
docs/ or package README location instead of projects/, and ensure link text and
relative path are adjusted so the doc remains valid and version-stable.
In `@skills-contrib/drive-create-project/SKILL.md`:
- Line 117: The markdown links in SKILL.md (e.g., the reference to
projects/drive-domain-model/principles/definition-of-ready.md and the other
similar link at line 125) point to transient project docs under projects/;
replace them with durable documentation targets such as the canonical docs/ path
or a package README (e.g., docs/principles/definition-of-ready.md or the
repo/package README that contains the Project DoR) so the SKILL.md references
link to long-lived docs rather than transient project artifacts.
In `@skills-contrib/drive-create-spec/SKILL.md`:
- Line 24: Replace the transient projects/drive-domain-model/design-decisions.md
link in the SKILL.md deprecation note with a durable target under docs/ (for
example docs/README.md or docs/drive-domain-model/README.md); specifically
locate the link text "`projects/drive-domain-model/design-decisions.md`" (and
any reference to "§ 17") in SKILL.md and update the href and visible text to
point to the chosen docs/ README so the deprecation guidance remains stable
after project close-out.
In `@skills-contrib/drive-deliver-workflow/SKILL.md`:
- Line 63: The SKILL.md contains durable-link violations: replace transient
links pointing at
"projects/drive-domain-model/principles/definition-of-ready.md" (and the other
occurrences around lines noted) with stable documentation targets such as the
canonical docs/ path or package README (e.g., docs/definition-of-ready.md or
docs/drive-domain-model/README.md); update the markdown links and link text in
SKILL.md to point to the durable docs/ or README file that contains the Project
Definition of Ready, and verify the target file exists (create or move the
content into docs/ if necessary) so all links reference stable documentation
instead of projects/.
- Around line 21-44: The fenced diagram block that documents the workflow (the
code fence containing "project spec + plan exist" and steps mentioning
drive-build-workflow, drive-check-health, drive-run-retro, etc.) lacks a fence
language and triggers markdown-lint warnings; add a language tag (for example
`text`) to the opening triple-backtick so the block becomes ```text ... ``` to
silence the lint warning without changing the diagram content.
In `@skills-contrib/drive-discussion/SKILL.md`:
- Line 15: The link in SKILL.md points to a transient projects/ path; update the
markdown link target to the durable docs location (e.g., replace
`projects/drive-domain-model/model.md` with the stable docs path such as
`docs/drive-domain-model/model.md` or the package README) so the reference is
permanent and follows the documentation guideline; edit the line containing
"Five canonical triggers (per [`projects/drive-domain-model/model.md`]..." to
use the durable doc link and verify the target file exists and renders
correctly.
In `@skills-contrib/drive-plan-project/SKILL.md`:
- Around line 199-202: Update the four markdown links in SKILL.md that currently
point to /projects/drive-domain-model/... so they reference durable locations
(docs/ or package README files) instead of transient project artifacts; locate
the lines containing the four links (the entries referencing model.md,
workflow.md, principles/decomposition-and-cost.md, and design-decisions.md) and
replace their hrefs with the corresponding stable paths under docs/ or the
package's README (or move content into docs/ and link there) while preserving
the link text and section annotations.
In `@skills-contrib/drive-plan-slice/SKILL.md`:
- Line 99: Replace the transient project link
"projects/drive-domain-model/principles/definition-of-ready.md" used in the
phrase "Per-dispatch DoR" (and the similar links at the later block referencing
the same project artifact) with a durable documentation link (e.g., the
canonical docs/ path or the package README that contains the Definition of
Ready). Update the markdown references in SKILL.md so the anchor points to a
stable docs/ URL or README file that will persist beyond the project tree,
preserving the link text "Per-dispatch DoR" and ensuring the destination
documents the same content.
In `@skills-contrib/drive-pr-description/SKILL.md`:
- Line 155: Replace the transient projects/ link in SKILL.md (the inline link
`/projects/drive-domain-model/model.md` referenced in the "drive-start-workflow"
line) with a durable docs target or package README; update the link to point to
a stable location such as a docs page (e.g., `/docs/drive-domain-model.md`) or
the repository package README that contains the same model information, and
ensure the link text and path are updated in the same line so the skill doc no
longer references a transient projects/ artifact.
In `@skills-contrib/drive-run-retro/SKILL.md`:
- Line 18: Replace the transient project link
`projects/drive-domain-model/principles/retro.md` in SKILL.md with a durable
documentation target (e.g., the canonical docs site page or a package README) so
the reference points to a stable surface; update all other similar occurrences
noted (lines referencing the same projects/ path at the indicated locations) to
use durable `docs/` or package README links instead and ensure link text and
context remain accurate.
In `@skills-contrib/drive-specify-project/SKILL.md`:
- Line 50: Replace transient `projects/drive-domain-model/...` links in SKILL.md
with durable documentation targets: find the markdown line that reads "Project
DoR (per [`projects/drive-domain-model/principles/definition-of-ready.md`] …)"
and the two other occurrences that reference `projects/drive-domain-model` (the
second occurrence near the "Project DoR" mention and the block referencing
drive-domain-model later in the file) and update each link to point to the
stable docs surface (e.g., the equivalent page under `docs/` or the package
README) and ensure link text remains meaningful; verify all three replacements
build correctly and remove any remaining `projects/drive-domain-model` links.
In `@skills-contrib/drive-start-workflow/SKILL.md`:
- Line 100: Replace the transient projects/ link in SKILL.md: locate the
occurrence that says "Load `drive/triage/README.md` at workflow step 1" and the
referenced path "projects/drive-domain-model/principles/protocol-as-memory.md"
(and the other similar occurrences later in the file) and update each to point
to a stable documentation surface (for example a docs/ permalink or the package
README like `docs/drive/protocol-as-memory.md` or `drive/README.md`) so the
durable skill doc no longer links to transient `projects/` artifacts; ensure
link text and any descriptive phrasing remain accurate after swapping the
target.
- Around line 19-57: The fenced workflow diagram block in SKILL.md is missing a
language tag which fails markdown linting; update the triple-backtick fence that
wraps the ASCII diagram (the block starting with "Entry point (Linear ticket /
bug / ask / mid-flight scope-shift signal)") to include a language identifier
such as "text" (e.g., ```text) so the diagram is properly labeled while
preserving its contents and formatting.
In `@skills-contrib/drive-triage-work/SKILL.md`:
- Around line 82-128: The fenced decision-tree block (the triple-backtick block
containing Q0–Q5) needs a language hint to satisfy markdown linting and tooling;
replace the opening fence ``` with a language-tagged fence such as ```text (or
another appropriate tag) so the decision-tree block is explicitly marked,
leaving the content unchanged.
- Around line 207-210: Replace the transient links under projects/ in SKILL.md
with durable documentation targets: swap each projects/drive-domain-model/...
reference (for model.md, workflow.md, principles/decomposition-and-cost.md,
principles/spikes.md) to the equivalent stable docs/ or package README paths (or
canonical doc permalinks) so the Triage workflow and principles links point to
long-lived documentation; update the link text if needed to match the new target
locations and verify the links resolve.
---
Outside diff comments:
In `@skills-contrib/drive-build-workflow/SKILL.md`:
- Around line 43-49: Search the SKILL.md for all occurrences of the legacy skill
names "drive-create-spec" and "drive-create-plan" (they appear in the "Do not
use this skill for" section and elsewhere) and replace them with the new split
skill families "drive-specify-*" for spec-related handoffs and "drive-plan-*"
for plan-related handoffs; update the surrounding guidance so the orchestration
contract explicitly routes spec work to drive-specify-* and plan work to
drive-plan-*, and ensure every mention in the file (including the earlier bullet
points and any guidance lines that currently reference
drive-create-spec/drive-create-plan) is updated to the new names so the handoff
guidance is consistent.
- Around line 205-215: The README shows inconsistent subcommand argument names:
change the documented usage of the three subcommands "/drive-build-workflow
iterate [milestone-id]", "/drive-build-workflow implement [milestone-id]", and
"/drive-build-workflow review" to use the canonical dispatch identifier used by
the protocol (e.g. "/drive-build-workflow iterate <dispatch-id>",
"/drive-build-workflow implement <dispatch-id>", "/drive-build-workflow review
<dispatch-id>") so all examples and the explanatory text refer to
"<dispatch-id>" (or the single canonical token used elsewhere like
"dispatch-id") instead of "[milestone-id]"; update the brief descriptions for
the iterate/implement/review lines and the example and any parenthetical note
that mentions mapping to plan.md to reference dispatch IDs consistently (look
for the command strings iterate/implement/review and the parenthetical mapping
to plan.md to make the replacements).
In `@skills-contrib/drive-discussion/SKILL.md`:
- Line 157: Update the docs to stop referencing the deprecated handoff skill
`drive-create-spec`; change the Outcome line to point to the new scoped split
handoff (e.g., `drive-specify-project` or `drive-specify-slice`) so it matches
the rest of the PR workflow contract and README guidance; ensure the wording and
target path (`projects/<project>/spec.md`) remain correct but route to the
appropriate new skill name used elsewhere in this PR.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 4fc637f8-f137-4ffb-9a7b-32e1f662d927
⛔ Files ignored due to path filters (18)
projects/drive-domain-model/README.mdis excluded by!projects/**projects/drive-domain-model/calibration/prisma-next.mdis excluded by!projects/**projects/drive-domain-model/design-decisions.mdis excluded by!projects/**projects/drive-domain-model/model.mdis excluded by!projects/**projects/drive-domain-model/plan.mdis excluded by!projects/**projects/drive-domain-model/principles/brief-discipline.mdis excluded by!projects/**projects/drive-domain-model/principles/decomposition-and-cost.mdis excluded by!projects/**projects/drive-domain-model/principles/definition-of-done.mdis excluded by!projects/**projects/drive-domain-model/principles/definition-of-ready.mdis excluded by!projects/**projects/drive-domain-model/principles/gradual-ai-adoption.mdis excluded by!projects/**projects/drive-domain-model/principles/protocol-as-memory.mdis excluded by!projects/**projects/drive-domain-model/principles/retro.mdis excluded by!projects/**projects/drive-domain-model/principles/roles-and-personas.mdis excluded by!projects/**projects/drive-domain-model/principles/spikes.mdis excluded by!projects/**projects/drive-domain-model/problem-statement.mdis excluded by!projects/**projects/drive-domain-model/skill-restructure.mdis excluded by!projects/**projects/drive-domain-model/spec.mdis excluded by!projects/**projects/drive-domain-model/workflow.mdis excluded by!projects/**
📒 Files selected for processing (32)
.gitignoredrive/README.mddrive/health/README.mddrive/plan/README.mddrive/pr/README.mddrive/project/README.mddrive/retro/README.mddrive/spec/README.mddrive/triage/README.mdskills-contrib/drive-build-workflow/SKILL.mdskills-contrib/drive-build-workflow/agents/implementer.mdskills-contrib/drive-build-workflow/agents/reviewer.mdskills-contrib/drive-build-workflow/templates/code-review.template.mdskills-contrib/drive-build-workflow/templates/delegate-implement.mdskills-contrib/drive-build-workflow/templates/delegate-review.mdskills-contrib/drive-build-workflow/templates/unattended-decisions.template.mdskills-contrib/drive-check-health/SKILL.mdskills-contrib/drive-code-review/SKILL.mdskills-contrib/drive-create-plan/SKILL.mdskills-contrib/drive-create-project/SKILL.mdskills-contrib/drive-create-spec/SKILL.mdskills-contrib/drive-deliver-workflow/SKILL.mdskills-contrib/drive-discussion/SKILL.mdskills-contrib/drive-plan-project/SKILL.mdskills-contrib/drive-plan-slice/SKILL.mdskills-contrib/drive-pr-description/SKILL.mdskills-contrib/drive-pr-local-review/SKILL.mdskills-contrib/drive-run-retro/SKILL.mdskills-contrib/drive-specify-project/SKILL.mdskills-contrib/drive-specify-slice/SKILL.mdskills-contrib/drive-start-workflow/SKILL.mdskills-contrib/drive-triage-work/SKILL.md
✅ Files skipped from review due to trivial changes (12)
- skills-contrib/drive-build-workflow/templates/delegate-implement.md
- skills-contrib/drive-build-workflow/templates/delegate-review.md
- skills-contrib/drive-build-workflow/templates/unattended-decisions.template.md
- skills-contrib/drive-build-workflow/agents/reviewer.md
- drive/pr/README.md
- drive/health/README.md
- drive/plan/README.md
- drive/project/README.md
- skills-contrib/drive-specify-slice/SKILL.md
- skills-contrib/drive-code-review/SKILL.md
- skills-contrib/drive-pr-local-review/SKILL.md
- skills-contrib/drive-create-plan/SKILL.md
wmadden
force-pushed
the
tml-2549-agile-agent-orchestration
branch
from
fa03911 to
6972db7
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@drive/retro/README.md`:
- Line 13: Update the malformed ADR path string in the README: replace the
incorrect fragment "docs/architecture docs/adrs/" with the correct path
"docs/architecture/adrs/" so the sentence reads "**Durable architectural
decisions** → ADR under `docs/architecture/adrs/`"; edit the README.md line
containing that path accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 1346f0c4-41de-4c5b-9f4b-92395e05c5a4
⛔ Files ignored due to path filters (18)
projects/drive-domain-model/README.mdis excluded by!projects/**projects/drive-domain-model/calibration/prisma-next.mdis excluded by!projects/**projects/drive-domain-model/design-decisions.mdis excluded by!projects/**projects/drive-domain-model/model.mdis excluded by!projects/**projects/drive-domain-model/plan.mdis excluded by!projects/**projects/drive-domain-model/principles/brief-discipline.mdis excluded by!projects/**projects/drive-domain-model/principles/decomposition-and-cost.mdis excluded by!projects/**projects/drive-domain-model/principles/definition-of-done.mdis excluded by!projects/**projects/drive-domain-model/principles/definition-of-ready.mdis excluded by!projects/**projects/drive-domain-model/principles/gradual-ai-adoption.mdis excluded by!projects/**projects/drive-domain-model/principles/protocol-as-memory.mdis excluded by!projects/**projects/drive-domain-model/principles/retro.mdis excluded by!projects/**projects/drive-domain-model/principles/roles-and-personas.mdis excluded by!projects/**projects/drive-domain-model/principles/spikes.mdis excluded by!projects/**projects/drive-domain-model/problem-statement.mdis excluded by!projects/**projects/drive-domain-model/skill-restructure.mdis excluded by!projects/**projects/drive-domain-model/spec.mdis excluded by!projects/**projects/drive-domain-model/workflow.mdis excluded by!projects/**
📒 Files selected for processing (32)
.gitignoredrive/README.mddrive/health/README.mddrive/plan/README.mddrive/pr/README.mddrive/project/README.mddrive/retro/README.mddrive/spec/README.mddrive/triage/README.mdskills-contrib/drive-build-workflow/SKILL.mdskills-contrib/drive-build-workflow/agents/implementer.mdskills-contrib/drive-build-workflow/agents/reviewer.mdskills-contrib/drive-build-workflow/templates/code-review.template.mdskills-contrib/drive-build-workflow/templates/delegate-implement.mdskills-contrib/drive-build-workflow/templates/delegate-review.mdskills-contrib/drive-build-workflow/templates/unattended-decisions.template.mdskills-contrib/drive-check-health/SKILL.mdskills-contrib/drive-code-review/SKILL.mdskills-contrib/drive-create-plan/SKILL.mdskills-contrib/drive-create-project/SKILL.mdskills-contrib/drive-create-spec/SKILL.mdskills-contrib/drive-deliver-workflow/SKILL.mdskills-contrib/drive-discussion/SKILL.mdskills-contrib/drive-plan-project/SKILL.mdskills-contrib/drive-plan-slice/SKILL.mdskills-contrib/drive-pr-description/SKILL.mdskills-contrib/drive-pr-local-review/SKILL.mdskills-contrib/drive-run-retro/SKILL.mdskills-contrib/drive-specify-project/SKILL.mdskills-contrib/drive-specify-slice/SKILL.mdskills-contrib/drive-start-workflow/SKILL.mdskills-contrib/drive-triage-work/SKILL.md
✅ Files skipped from review due to trivial changes (17)
- skills-contrib/drive-build-workflow/templates/delegate-review.md
- skills-contrib/drive-build-workflow/templates/delegate-implement.md
- skills-contrib/drive-build-workflow/agents/implementer.md
- skills-contrib/drive-build-workflow/templates/unattended-decisions.template.md
- skills-contrib/drive-build-workflow/agents/reviewer.md
- skills-contrib/drive-specify-project/SKILL.md
- drive/pr/README.md
- drive/project/README.md
- drive/triage/README.md
- skills-contrib/drive-pr-local-review/SKILL.md
- drive/health/README.md
- drive/plan/README.md
- .gitignore
- skills-contrib/drive-run-retro/SKILL.md
- skills-contrib/drive-create-project/SKILL.md
- skills-contrib/drive-create-spec/SKILL.md
- skills-contrib/drive-create-plan/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (4)
- skills-contrib/drive-code-review/SKILL.md
- skills-contrib/drive-specify-slice/SKILL.md
- skills-contrib/drive-check-health/SKILL.md
- skills-contrib/drive-build-workflow/SKILL.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@drive/retro/README.md`:
- Line 13: Update the broken relative link target
`docs/architecture%20docs/adrs/` in drive/retro/README.md so it correctly points
to the ADR directory at the repository root by prepending the correct upward
path; replace it with `../../docs/architecture%20docs/adrs/` (keeping the
existing percent-encoding) so the link resolves from the current file location,
i.e., change the link text that contains `docs/architecture%20docs/adrs/` to
`../../docs/architecture%20docs/adrs/`.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: c7db4d59-aaad-4f5d-942d-4444a8b80917
📒 Files selected for processing (1)
drive/retro/README.md
Merged
3 tasks
wmadden
added a commit
that referenced
this pull request
May 19, 2026
drive-close-project step 7: external-reference strip after migration. Cross-references re-pointed to their new homes: - skills-contrib/drive-specify-slice/SKILL.md: model.md, principles/*, design-decisions.md refs -> docs/drive/* equivalents (the design-decisions ref repoints to skill-conventions.md since the raw ledger is transient and doesn't survive close-out). - skills-contrib/drive-create-spec/SKILL.md: design-decisions.md ref -> docs/drive/skill-conventions.md (where the split rationale lives as durable methodology). - skills-contrib/drive-create-plan/SKILL.md: same as above; also drops "(D9 + D24)" decision-ID inline citation since those IDs are about to disappear with the ledger. Migrated-doc cross-references within docs/drive/: - skill-restructure.md -> skill-conventions.md (rename) throughout. - spec.md / plan.md / design-decisions.md references either re-framed as inline prose or repointed at PR #522 (the close-out PR carries the project's commit history, which preserves the decision log). - New trial.md cross-references added where the migration removed references to plan.md's "build-then-trial-then-upstream" sequencing. .gitignore: the projects/drive-domain-model/reference/ exclusion generalised to projects/*/reference/ so future projects can opt into the same "browse local clones, don't commit" convention without gitignore touches. Re-scan returns clean (one false positive remains in calibration prose where the project's history references a 2026-05-17 agent-deletion incident; war-story text, not a link). Signed-off-by: Will Madden <madden@prisma.io>
wmadden
added a commit
that referenced
this pull request
May 19, 2026
drive-close-project step 8: deletion. Long-lived methodology lives at docs/drive/; the transient project scaffolding (spec, plan, README, design-decisions, retros) was retired by this commit. What's deleted: - spec.md (shaping artefact; acceptance criteria verified at step 2 -- AC1-AC7, AC17 met; AC8-AC18 deferred to TML-2567 by design). - plan.md (coordination artefact; execution complete). - README.md (project orientation; superseded by docs/drive/README.md). - design-decisions.md (chronological alternatives ledger; the durable rationale was either inlined into the migrated docs or remains in the PR #522 commit history for archeology). - retros.md (mandatory-final retro entry; lessons landed in the surfaces accounted for in the retro itself per invariant I10). What's preserved (already migrated at step 6): - docs/drive/principles/*.md (9 principle docs) - docs/drive/model.md, workflow.md, problem-statement.md - docs/drive/skill-conventions.md (renamed from skill-restructure.md) - docs/drive/calibration/prisma-next.md - docs/drive/trial.md (trial framing for the validation window) - docs/drive/README.md (entry-point index for the migrated material) Linked issue: TML-2549. Linked synthesis ticket: TML-2567. Signed-off-by: Will Madden <madden@prisma.io>
wmadden
added a commit
that referenced
this pull request
May 19, 2026
Per PR #533 review comments 3264049516 + 3264049883: project-specific review knowledge belongs in `drive/<workflow>/README.md` (convention introduced on #522), not in generic `skills-contrib/drive-*/SKILL.md` bodies. - Revert the "Smells to surface during the principal-engineer pass" section added to `skills-contrib/drive-code-review/SKILL.md` and `skills-contrib/drive-pr-local-review/SKILL.md`. - Create `drive/code/README.md` (missing category README) carrying the `as Contract` smell entry, structured like `drive/qa/README.md`. #522 (which introduces the `drive/<workflow>/README.md` convention) can land independently — no conflict.
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
drive/retro/README.md (1)
15-15:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix the relative link path.
The link target
docs/architecture%20docs/adrs/is relative to the current file location (drive/retro/README.md), so it would incorrectly resolve todrive/retro/docs/architecture%20docs/adrs/. To correctly navigate to the ADR directory at the repository root, the path needs../../prefix.🔗 Proposed fix
-- **Durable architectural decisions** → ADR under [docs/architecture docs/adrs/](docs/architecture%20docs/adrs/). +- **Durable architectural decisions** → ADR under [docs/architecture docs/adrs/](../../docs/architecture%20docs/adrs/).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@drive/retro/README.md` at line 15, The relative link "docs/architecture%20docs/adrs/" in drive/retro/README.md is missing the repository-root prefix so it resolves under drive/retro; update that link to include the parent-path prefix (change "docs/architecture%20docs/adrs/" to "../../docs/architecture%20docs/adrs/") so it correctly points to the ADR directory at the repo root; ensure the percent-encoding for the space ("%20") is preserved in the link text.
🧹 Nitpick comments (6)
skills-contrib/drive-close-project/SKILL.md (1)
123-127: ⚡ Quick winAdd language specifier to fenced code block.
The code block showing the classification record format should have a language identifier for proper rendering and linting compliance.
📝 Suggested fix
-``` +```text <path> → long-lived | transient | ambiguous destination (if long-lived): docs/<project>/<sub-path> rationale (one line)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills-contrib/drive-close-project/SKILL.md` around lines 123 - 127, The fenced code block that contains the classification record format (the block starting with "<path> → long-lived | transient | ambiguous" and the following lines) is missing a language identifier; add a language specifier (e.g., "text") after the opening triple backticks so the block becomes ```text to ensure correct rendering and linting compliance.docs/drive/model.md (1)
7-27: ⚡ Quick winAdd language specifier to fenced code block.
The block showing the domain model overview should have a language identifier for proper rendering.
📝 Suggested fix
-``` +```text Sized units (smallest → largest): Direct change → Slice → Project (no spec) (one PR) (composes slices)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/model.md` around lines 7 - 27, The fenced code block containing the domain model overview needs a language specifier so it renders correctly; update the opening triple-backtick for that block (the block that starts with "Sized units (smallest → largest): ...") to include a language identifier such as "text" (e.g., change ``` to ```text) so the renderer treats it as plain text and preserves formatting.docs/drive/principles/roles-and-personas.md (1)
68-107: 💤 Low valueConsider adding language specifiers to fenced code blocks.
The four configuration example blocks (lines 68-73, 79-85, 90-95, 101-107) lack language specifiers. While this doesn't affect rendering, adding
textoryamlidentifiers would improve tooling support and satisfy linters.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/principles/roles-and-personas.md` around lines 68 - 107, The four fenced code blocks under sections A–D (the blocks starting with "Project owner: operator" and the subsequent three examples) lack language specifiers; update each triple-backtick fence to include a language tag such as text or yaml (e.g., ```text) so linters and tooling can correctly recognize them—edit each block in the roles-and-personas.md content where those examples appear to add the specifier.docs/drive/principles/definition-of-ready.md (1)
9-10: 💤 Low valueConsider using placeholder paths in the worked example.
Lines 9-10 reference specific transient project artifacts (
projects/storage-shape-flatten/...) in durable methodology documentation. While these are illustrative examples rather than live links, concrete project references can become stale over time. Consider using placeholder syntax (projects/<project>/slices/<slice>/spec.md) similar to line 53, or reference a hypothetical example project name.Based on learnings: "Do not reference transient project artifacts (e.g., under projects/ such as specs, plans, milestone documents) from durable system documentation (package READMEs, architecture/docs under docs/)."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/principles/definition-of-ready.md` around lines 9 - 10, Replace the concrete transient example paths "projects/storage-shape-flatten/slices/round-2/spec.md" and "projects/storage-shape-flatten/slices/round-2/plan.md" with placeholder syntax (e.g., "projects/<project>/slices/<slice>/spec.md" and "projects/<project>/slices/<slice>/plan.md") or a clearly marked hypothetical project name so the durable documentation doesn't reference transient project artifacts; update the two lines that currently contain those exact strings to use the placeholder form consistent with the example on line 53.docs/drive/problem-statement.md (1)
19-19: ⚡ Quick winReference to transient
wip/artifact in durable docs.The reference to
wip/unattended-decisions.mdpoints to a transient surface (wip/ is "no-memory" per the retro principle). For durable documentation, consider either: (1) briefly describing the incident inline rather than citing the wip/ file, or (2) if the decision log is important to preserve, migrating relevant excerpts to a more durable surface likedocs/drive/calibration/or an ADR.Based on learnings: "Do not reference transient project artifacts (e.g., under projects/ such as specs, plans, milestone documents) from durable system documentation."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/problem-statement.md` at line 19, The docs/drive/problem-statement.md contains an impermanent reference to "wip/unattended-decisions.md"; remove or replace that transient reference by either (A) copying the essential incident summary directly into problem-statement.md as a brief inline description (preserving the sentence about single dispatch, file-system proxies, grep gate escape, CI passing, failure surfacing three slices later and recovery cost), or (B) migrate the relevant excerpts into a durable location (for example create a new file under docs/drive/calibration/ or an ADR) and update problem-statement.md to point to that durable file; ensure the string "wip/unattended-decisions.md" is deleted/updated and add a short note indicating where the preserved decision now lives.skills-contrib/drive-update-skills/SKILL.md (1)
29-29: ⚡ Quick winPrefer ASCII arrows over Unicode symbols.
Lines 29, 90, and 109 use the Unicode arrow
→instead of ASCII alternatives. For better portability and consistency across documentation, consider using->or spelling out the relationship.📝 Proposed ASCII alternatives
Line 29:
-- In-repo drive-* skill bodies are not byte-identical to canonical (drift detected). → `drive-reconcile-skills` first; then come back. +- In-repo drive-* skill bodies are not byte-identical to canonical (drift detected). -> `drive-reconcile-skills` first; then come back.Line 90:
-- **Disappeared** (section removed, file moved) → flag as a *broken* reference. Propose a patch (delete the reference, or point at the closest surviving anchor with a `<!-- TODO: verify -->` comment). +- **Disappeared** (section removed, file moved) -> flag as a *broken* reference. Propose a patch (delete the reference, or point at the closest surviving anchor with a `<!-- TODO: verify -->` comment).Line 109:
-- `<n> drive-* skills updated` from `<old-sha>` → `<new-sha>` of canonical. +- `<n> drive-* skills updated` from `<old-sha>` -> `<new-sha>` of canonical.As per coding guidelines: Prefer ASCII in documentation (avoid arrows like
→in markdown files).Also applies to: 90-90, 109-109
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills-contrib/drive-update-skills/SKILL.md` at line 29, Replace the Unicode arrow character "→" with an ASCII alternative (e.g., "->" or the words "then") in the SKILL.md occurrences where the document reads things like "In-repo drive-* skill bodies are not byte-identical ... → `drive-reconcile-skills` first; then come back." (also present at the other two occurrences). Search for the literal "→" in SKILL.md and update each instance to "->" (or rewrite the phrase to use "then") so the documentation uses only ASCII characters.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@drive/retro/README.md`:
- Line 15: The relative link "docs/architecture%20docs/adrs/" in
drive/retro/README.md is missing the repository-root prefix so it resolves under
drive/retro; update that link to include the parent-path prefix (change
"docs/architecture%20docs/adrs/" to "../../docs/architecture%20docs/adrs/") so
it correctly points to the ADR directory at the repo root; ensure the
percent-encoding for the space ("%20") is preserved in the link text.
---
Nitpick comments:
In `@docs/drive/model.md`:
- Around line 7-27: The fenced code block containing the domain model overview
needs a language specifier so it renders correctly; update the opening
triple-backtick for that block (the block that starts with "Sized units
(smallest → largest): ...") to include a language identifier such as "text"
(e.g., change ``` to ```text) so the renderer treats it as plain text and
preserves formatting.
In `@docs/drive/principles/definition-of-ready.md`:
- Around line 9-10: Replace the concrete transient example paths
"projects/storage-shape-flatten/slices/round-2/spec.md" and
"projects/storage-shape-flatten/slices/round-2/plan.md" with placeholder syntax
(e.g., "projects/<project>/slices/<slice>/spec.md" and
"projects/<project>/slices/<slice>/plan.md") or a clearly marked hypothetical
project name so the durable documentation doesn't reference transient project
artifacts; update the two lines that currently contain those exact strings to
use the placeholder form consistent with the example on line 53.
In `@docs/drive/principles/roles-and-personas.md`:
- Around line 68-107: The four fenced code blocks under sections A–D (the blocks
starting with "Project owner: operator" and the subsequent three examples)
lack language specifiers; update each triple-backtick fence to include a
language tag such as text or yaml (e.g., ```text) so linters and tooling can
correctly recognize them—edit each block in the roles-and-personas.md content
where those examples appear to add the specifier.
In `@docs/drive/problem-statement.md`:
- Line 19: The docs/drive/problem-statement.md contains an impermanent reference
to "wip/unattended-decisions.md"; remove or replace that transient reference by
either (A) copying the essential incident summary directly into
problem-statement.md as a brief inline description (preserving the sentence
about single dispatch, file-system proxies, grep gate escape, CI passing,
failure surfacing three slices later and recovery cost), or (B) migrate the
relevant excerpts into a durable location (for example create a new file under
docs/drive/calibration/ or an ADR) and update problem-statement.md to point to
that durable file; ensure the string "wip/unattended-decisions.md" is
deleted/updated and add a short note indicating where the preserved decision now
lives.
In `@skills-contrib/drive-close-project/SKILL.md`:
- Around line 123-127: The fenced code block that contains the classification
record format (the block starting with "<path> → long-lived | transient |
ambiguous" and the following lines) is missing a language identifier; add a
language specifier (e.g., "text") after the opening triple backticks so the
block becomes ```text to ensure correct rendering and linting compliance.
In `@skills-contrib/drive-update-skills/SKILL.md`:
- Line 29: Replace the Unicode arrow character "→" with an ASCII alternative
(e.g., "->" or the words "then") in the SKILL.md occurrences where the document
reads things like "In-repo drive-* skill bodies are not byte-identical ... →
`drive-reconcile-skills` first; then come back." (also present at the other two
occurrences). Search for the literal "→" in SKILL.md and update each instance to
"->" (or rewrite the phrase to use "then") so the documentation uses only ASCII
characters.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: d8161afb-54c5-43a0-aae0-248d1f3c1416
📒 Files selected for processing (52)
.agents/rules/drive-project-workflow.mdc.gitignoredocs/drive/README.mddocs/drive/calibration/prisma-next.mddocs/drive/model.mddocs/drive/principles/brief-discipline.mddocs/drive/principles/decomposition-and-cost.mddocs/drive/principles/definition-of-done.mddocs/drive/principles/definition-of-ready.mddocs/drive/principles/gradual-ai-adoption.mddocs/drive/principles/protocol-as-memory.mddocs/drive/principles/retro.mddocs/drive/principles/roles-and-personas.mddocs/drive/principles/spikes.mddocs/drive/problem-statement.mddocs/drive/skill-conventions.mddocs/drive/trial.mddocs/drive/workflow.mddrive/health/README.mddrive/health/findings.mddrive/plan/README.mddrive/plan/findings.mddrive/pr/README.mddrive/pr/findings.mddrive/project/README.mddrive/project/findings.mddrive/qa/README.mddrive/qa/findings.mddrive/retro/README.mddrive/retro/findings.mddrive/spec/README.mddrive/spec/findings.mddrive/triage/README.mddrive/triage/findings.mdskills-contrib/drive-bootstrap-context/SKILL.mdskills-contrib/drive-bootstrap-context/templates/code-review.mdskills-contrib/drive-bootstrap-context/templates/deployment.mdskills-contrib/drive-bootstrap-context/templates/health.mdskills-contrib/drive-bootstrap-context/templates/plan.mdskills-contrib/drive-bootstrap-context/templates/post-update.mdskills-contrib/drive-bootstrap-context/templates/pr.mdskills-contrib/drive-bootstrap-context/templates/project.mdskills-contrib/drive-bootstrap-context/templates/qa.mdskills-contrib/drive-bootstrap-context/templates/retro.mdskills-contrib/drive-bootstrap-context/templates/spec.mdskills-contrib/drive-bootstrap-context/templates/triage.mdskills-contrib/drive-close-project/SKILL.mdskills-contrib/drive-create-plan/SKILL.mdskills-contrib/drive-create-spec/SKILL.mdskills-contrib/drive-reconcile-skills/SKILL.mdskills-contrib/drive-specify-slice/SKILL.mdskills-contrib/drive-update-skills/SKILL.md
✅ Files skipped from review due to trivial changes (24)
- .gitignore
- drive/pr/findings.md
- drive/qa/findings.md
- skills-contrib/drive-bootstrap-context/templates/deployment.md
- drive/retro/findings.md
- drive/spec/findings.md
- drive/project/findings.md
- drive/triage/findings.md
- skills-contrib/drive-bootstrap-context/templates/spec.md
- skills-contrib/drive-bootstrap-context/templates/triage.md
- skills-contrib/drive-bootstrap-context/templates/retro.md
- skills-contrib/drive-bootstrap-context/templates/qa.md
- docs/drive/README.md
- skills-contrib/drive-bootstrap-context/templates/post-update.md
- drive/health/findings.md
- skills-contrib/drive-bootstrap-context/templates/code-review.md
- drive/plan/findings.md
- skills-contrib/drive-bootstrap-context/SKILL.md
- skills-contrib/drive-bootstrap-context/templates/health.md
- drive/health/README.md
- skills-contrib/drive-bootstrap-context/templates/plan.md
- skills-contrib/drive-specify-slice/SKILL.md
- skills-contrib/drive-create-spec/SKILL.md
- skills-contrib/drive-create-plan/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (3)
- drive/triage/README.md
- drive/plan/README.md
- drive/pr/README.md
Contributor
Author
|
Thanks for the detailed review. All five findings have been addressed in the commits that followed this review batch: (1) circular reference in description corrected to 'drive-orchestrate-plan'; (2) 'atomic' vs auto-invoke contradiction resolved; (3) wrong skill name 'drive-project-specify' fixed to 'drive-specify-project'; (4) ASCII diagram in drive-start-workflow updated to correct skill names; (5) transient projects/ links removed from drive/README.md. No further action needed here. |
Contributor
Author
|
Thanks — all 16 findings verified as addressed in commits following this review. Transient projects/drive-domain-model links removed (zero remaining), skill names corrected throughout, code fence language tags added, subcommand args updated from milestone-id to dispatch-id, deprecated drive-create-spec/drive-create-plan references replaced with drive-specify-/drive-plan- in routing context. One mention of 'drive-create-plan' remains at line ~602 as advisory prose ('consider invoking ... for a fresh take') rather than a routing instruction — acceptable given this is a direct suggestion, not a handoff contract. |
Contributor
Author
|
The link in drive/retro/README.md has been fixed (commit 7d3d65b). Used '../../docs/architecture%20docs/adrs/' with correct percent-encoding to match the actual directory name — not 'docs/architecture/adrs/' which would drop the space in the folder name. |
Contributor
Author
|
Done — broken relative link in drive/retro/README.md fixed in commit 7d3d65b. |
Contributor
Author
|
Already fixed — commit 7d3d65b corrected the relative link to |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/drive/model.md`:
- Around line 7-27: The fenced block starting with "Sized units (smallest →
largest):" is missing a language tag which trips markdown linting; update that
opening triple-backtick to include a language identifier (e.g., add "text" after
the backticks) so the code fence becomes ```text and leave the closing ```
unchanged, ensuring the block renders and passes the linter.
In `@drive/pr/README.md`:
- Around line 9-11: Unify the PR title convention by choosing one canonical
format (preferably the conventional-commit style) and update all three sections
to match it: use the conventional-commit prefix (e.g.,
feat:/fix:/chore:/docs:/refactor:/test:/build:/ci:) plus a Linear ticket as a
suffix in the form `(TML-NNNN)` or a `Refs: TML-NNNN` line; remove or replace
the alternate `tml-XXXX:` prefix references and make the same change for the
other occurrences noted (the sections around the currently conflicting lines and
the other places referenced as 52-53 and 65-67) so the README only documents the
single chosen format consistently.
In `@drive/spec/README.md`:
- Line 47: The slice DoD rule uses an incorrect path pattern
`packages/3-*-extensions/**`; update this to the repo's actual extension
directory pattern (e.g., `packages/3-*-extension/**`) so the rule matches
correctly, and keep the rest of the sentence intact: "If the slice touches
`packages/3-*-extension/**`, the slice plan must include a `pnpm fixtures:check`
dispatch step." Locate and edit the string `packages/3-*-extensions/**` in the
README (the slice-DoD rule) and replace it with the correct pattern used
elsewhere in the repo.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 84ac77fa-8a3b-47e9-b49e-0fae6c83e701
📒 Files selected for processing (9)
docs/drive/README.mddocs/drive/model.mddocs/drive/problem-statement.mddrive/README.mddrive/plan/README.mddrive/pr/README.mddrive/project/README.mddrive/qa/README.mddrive/spec/README.md
✅ Files skipped from review due to trivial changes (1)
- docs/drive/README.md
wmadden
added a commit
that referenced
this pull request
May 19, 2026
Applies the prose audit from drive-close-project (per the
trial-period finding under drive/project/findings.md) to the
docs/drive/ tree. This is the cleanup half of the follow-up;
the rewrite half (workflow.md / model.md / worked examples) lands as
a separate slice.
Files removed (reclassified-as-transient):
- docs/drive/problem-statement.md -- a proposal letter to canonical
maintainers ("What we kept going wrong / What we are proposing /
What we would like from you"). Project-shaping artefact; PR #522
description preserves the narrative for anyone who needs it.
- docs/drive/skill-conventions.md -- titled "Skill restructuring
plan", with "What changes from current to final", "Build
sequencing", "Upstream promotion (later)". Project execution plan;
the resulting state lives in model.md / workflow.md / the
skill bodies themselves.
Content lifted into model.md before deletion:
- The naming convention from skill-conventions.md is now in
docs/drive/model.md as a new "Naming convention" subsection under
"Two skill tiers: workflow and atomic" -- the only piece of
enduring methodology buried in the restructuring plan.
File moved (reclassified as project context):
- docs/drive/trial.md -> drive/trial.md. The 2026-05-19 -> 2026-06-02
trial window is project-execution context tied to TML-2567, not
enduring methodology. Pointer blocks in all 8 drive/<category>/
READMEs + 8 findings.md files re-pointed at ../trial.md.
Worked-example sections lifted into project context (per the
calibration/** rule):
- docs/drive/principles/definition-of-ready.md "Worked example for
prisma-next:" block -- the content (Project / Slice / Dispatch
DoR overlays) already lives in drive/project/README.md,
drive/spec/README.md, drive/plan/README.md after the calibration
redistribution. Replaced with a one-line pointer at ../../drive/.
- docs/drive/principles/definition-of-done.md "Worked example for
prisma-next:" block -- same. Content already in drive/project/,
drive/pr/, drive/qa/, drive/plan/ READMEs. Replaced with pointer.
External references re-pointed:
- skills-contrib/drive-create-plan / drive-create-spec /
drive-specify-slice SKILL.md bodies: refs to skill-conventions.md
-> model.md § Two skill tiers.
- docs/drive/principles/gradual-ai-adoption.md ref to
skill-conventions.md -> model.md anchor.
- docs/drive/workflow.md ref to skill-conventions.md -> skills-contrib/
+ model.md naming-convention anchor.
- docs/drive/model.md three references re-pointed or removed.
- docs/drive/README.md trimmed: reading guide drops problem-statement,
drops the skill-conventions entry; trial entry re-pointed at
drive/trial.md and re-framed as project context; status footer
trimmed (was tied to the trial); migration-history footer dropped
(project-historical).
Linked issue: TML-2549. Linked finding: drive/project/findings.md
2026-05-19. Trial-period contribution to TML-2567 upstream synthesis.
Signed-off-by: Will Madden <madden@prisma.io>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
♻️ Duplicate comments (1)
drive/spec/README.md (1)
47-47:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse the canonical extensions path pattern in the DoD rule.
packages/3-*-extensions/**is likely the wrong surface and can misroutefixtures:checkgating; use the canonicalpackages/3-extensions/**path instead.Suggested patch
-- If the slice touches `packages/3-*-extensions/**`, the slice plan must include a `pnpm fixtures:check` dispatch step. +- If the slice touches `packages/3-extensions/**`, the slice plan must include a `pnpm fixtures:check` dispatch step.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@drive/spec/README.md` at line 47, Update the DoD rule text that references the extensions path: replace the incorrect pattern "packages/3-*-extensions/**" with the canonical "packages/3-extensions/**" so the slice plan correctly detects extensions and includes the required "pnpm fixtures:check" dispatch step (update the README line that currently reads the old pattern).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/drive/principles/decomposition-and-cost.md`:
- Line 38: In the sentence starting with "**Bounded recovery cost.**" replace
the nonstandard word "revertable" with a standard form like "reversible" (so the
sentence reads "...is trivially reversible.") to fix the typo and ensure
consistent user-facing terminology; update the phrase containing "revertable"
accordingly.
In `@docs/drive/principles/gradual-ai-adoption.md`:
- Around line 7-15: The Markdown code fence that contains the AI spectrum table
is unlabeled and triggers MD040; update the opening fence from ``` to a labeled
fence like ```text (or ```plain) so the block is explicitly marked as text —
locate the triple-backtick opening that precedes the "Zero AI ... Full
delegation" table and replace it with ```text to satisfy the linter.
In `@docs/drive/principles/protocol-as-memory.md`:
- Line 13: Update the mapping table row that currently references the skill name
"drive-review-code" to use the canonical skill name "drive-code-review" so links
and references point to the correct skill; locate the entry in
protocol-as-memory.md where "drive-review-code" appears and replace it with
"drive-code-review" (preserve surrounding formatting and casing).
- Around line 7-28: The fenced code block that contains the repository tree in
protocol-as-memory.md is missing a language tag and trips markdown linting; fix
it by adding a language identifier (e.g., "text") to the opening triple-backtick
fence that precedes the "your-repo/" tree (the fenced code block shown in the
diff), leaving the content and closing triple-backticks unchanged so the
markdown linter accepts the block.
In `@docs/drive/principles/retro.md`:
- Around line 96-97: Remove the documented example
"projects/<x>/retros/<date>.md" from the retro landing-surface guidance and
replace it with a sentence that disallows referencing transient project
artifacts in durable docs (e.g., state that retros must be committed to a
canonical durable location and not referenced under transient project paths);
update the adjacent sentence that mentions "protocol-as-memory.md" only if it
implies transient tiers so it doesn't normalize transient project paths.
In `@skills-contrib/drive-close-project/SKILL.md`:
- Around line 69-74: Step 2's acceptance-state list and the checklist are
inconsistent: Step 2 lists "Met | Deferred | Unmet" while the checklist uses
"cancelled-with-rationale"; choose one canonical model and make both places
match. Edit the SKILL.md content around "Step 2" to either add
"cancelled-with-rationale" to the Step 2 states or remove/replace
"cancelled-with-rationale" from the checklist so both use the same set, and
update any example text that references those states to use the chosen canonical
term (reference the "Step 2" heading and the checklist block that contains
"cancelled-with-rationale").
- Around line 125-129: The fenced code block containing "<path> → long-lived |
transient | ambiguous" in SKILL.md is missing a language tag and triggers MD040;
update the opening fence for that block from ``` to ```text (i.e., add the
"text" tag) so the snippet is explicitly marked and satisfies markdown linting.
---
Duplicate comments:
In `@drive/spec/README.md`:
- Line 47: Update the DoD rule text that references the extensions path: replace
the incorrect pattern "packages/3-*-extensions/**" with the canonical
"packages/3-extensions/**" so the slice plan correctly detects extensions and
includes the required "pnpm fixtures:check" dispatch step (update the README
line that currently reads the old pattern).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 66bfa09a-2368-40d5-97eb-d4b1bbc440f6
📒 Files selected for processing (33)
docs/drive/README.mddocs/drive/model.mddocs/drive/principles/brief-discipline.mddocs/drive/principles/decomposition-and-cost.mddocs/drive/principles/definition-of-done.mddocs/drive/principles/definition-of-ready.mddocs/drive/principles/gradual-ai-adoption.mddocs/drive/principles/protocol-as-memory.mddocs/drive/principles/retro.mddocs/drive/principles/spikes.mddocs/drive/workflow.mddrive/health/README.mddrive/health/findings.mddrive/plan/README.mddrive/plan/findings.mddrive/pr/README.mddrive/pr/findings.mddrive/project/README.mddrive/project/findings.mddrive/qa/README.mddrive/qa/findings.mddrive/retro/README.mddrive/retro/findings.mddrive/spec/README.mddrive/spec/findings.mddrive/triage/README.mddrive/triage/findings.mddrive/trial.mdskills-contrib/drive-close-project/SKILL.mdskills-contrib/drive-create-plan/SKILL.mdskills-contrib/drive-create-spec/SKILL.mdskills-contrib/drive-specify-slice/SKILL.mdskills-contrib/drive-start-workflow/SKILL.md
✅ Files skipped from review due to trivial changes (13)
- drive/plan/findings.md
- drive/health/findings.md
- drive/health/README.md
- drive/spec/findings.md
- drive/pr/findings.md
- drive/qa/findings.md
- drive/retro/findings.md
- skills-contrib/drive-specify-slice/SKILL.md
- skills-contrib/drive-create-plan/SKILL.md
- drive/pr/README.md
- drive/triage/findings.md
- skills-contrib/drive-start-workflow/SKILL.md
- docs/drive/principles/spikes.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/drive/README.md
- skills-contrib/drive-create-spec/SKILL.md
- drive/qa/README.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (6)
docs/drive/principles/decomposition-and-cost.md (1)
38-38:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix typo in user-facing wording (“revertable”).
Line 38 should use a standard form like
reversible(orrevertible) for clarity and consistency.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/principles/decomposition-and-cost.md` at line 38, Replace the nonstandard word "revertable" in the sentence that starts with "**Bounded recovery cost.**" (the phrase ending "...is trivially revertable.") with a standard term such as "reversible" (or "revertible") so the line reads "...is trivially reversible." to improve clarity and consistency in user-facing wording.drive/pr/README.md (1)
15-17:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winResolve conflicting PR title rules in one canonical convention.
Line 15-17 requires conventional-commit titles, but Line 59 reintroduces
<tml-id>:prefix format. Keep only one rule and align both sections to it.Also applies to: 59-60
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@drive/pr/README.md` around lines 15 - 17, Resolve the conflicting PR title rules by choosing the conventional-commit convention and removing the alternate `<tml-id>:` prefix rule; update the README so that the earlier rule "Conventional-commit prefix: `feat:` / `fix:` / `chore:` / `docs:` / `refactor:` / `test:` / `build:` / `ci:`" is the single canonical requirement and remove or replace the `<tml-id>:` reference (and any text that reintroduces it) so both sections consistently require a conventional-commit prefix plus the Linear ticket as either a `(TML-NNNN)` suffix or `Refs: TML-NNNN` in the description.docs/drive/model.md (1)
7-27:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a language tag to the fenced block.
The code fence starting at Line 7 should include a language identifier (for example,
text) to satisfy markdown linting consistency.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/model.md` around lines 7 - 27, The fenced code block that begins with "Sized units (smallest → largest):" should include a markdown language identifier to satisfy linting (e.g., change the opening ``` to ```text or ```txt); update the opening fence in docs/drive/model.md for that block so the markdown linter recognizes it as a text/code block.docs/drive/principles/gradual-ai-adoption.md (1)
7-15:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a language tag to the fenced spectrum block.
Line 7 opens an unlabeled fence, which still trips MD040 in markdown lint.
Suggested patch
-``` +```text Zero AI Full delegation ─────────────────────────────────────────────────────────────────────────────── Human reads, writes, Human invokes atomic Human invokes workflow Agent runs the ... -``` +```🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/principles/gradual-ai-adoption.md` around lines 7 - 15, The fenced code block that contains the spectrum table starting with "Zero AI Full delegation" is unlabeled and triggers MD040; update the opening fence from ``` to ```text (i.e., add the "text" language tag) while keeping the closing fence unchanged so the block is properly labeled for the linter.docs/drive/principles/protocol-as-memory.md (1)
7-28:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winLabel the repo-tree code fence.
Line 7 is still an unlabeled fenced block, so markdown lint MD040 remains.
Suggested patch
-``` +```text your-repo/ ├── drive/ ... -``` +```🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/principles/protocol-as-memory.md` around lines 7 - 28, The fenced code block showing the repo tree is unlabeled which triggers markdown lint MD040; update the opening fence from ``` to ```text (i.e., change the unlabeled ``` that precedes the "your-repo/" tree in protocol-as-memory.md to ```text) so the block is explicitly labeled as text and the linter warning is resolved.docs/drive/principles/retro.md (1)
95-96:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDon’t prescribe
projects/<x>/...as a retro landing surface in durable principles docs.This guidance normalizes transient project paths as an intermediate home, which conflicts with the durable-doc policy for repository docs.
Suggested patch
-Transient retros — drafts during a project's lifetime — may land first in `projects/<x>/retros/<date>.md` while the operator decides whether they're team-context-worthy or canonical-worthy. The transient surface is not memory (per [`protocol-as-memory.md`](protocol-as-memory.md)'s tier table); the retro is not done until the final home is committed. +Transient retro drafting should stay in durable tracked surfaces (for example, the relevant `drive/<category>/README.md` staging section or a tracked docs note) while the operator decides whether the update is team-context or canonical. The retro is not done until the final durable home is committed.Based on learnings: “Do not reference transient project artifacts (e.g., under projects/) from durable system documentation … Apply this pattern to all Markdown documentation files (READMEs and docs) across the repo.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/drive/principles/retro.md` around lines 95 - 96, The durable principles doc currently prescribes a transient project path by name ("projects/<x>/retros/<date>.md"); remove or reword that explicit path so the document does not normalize project-specific transient locations as a durable landing surface — replace the sentence referencing "projects/<x>/retros/<date>.md" with guidance that retros may be drafted in project-local (transient) locations but durable principles must not reference or rely on those transient paths, and instead point readers to use the repository's canonical/canonicalized retros or durable documentation locations per the "do not reference transient project artifacts" policy.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@drive/calibration/failure-modes.md`:
- Line 11: Update the broken sibling-doc link in the text that currently
references `[dor.md](./dor.md)` so it points to the correct file
`[dod.md](./dod.md)`; find the sentence "Patterns to **catch** the F-family
modes..." (the link token `dor.md`) and replace that link target with `dod.md`
to avoid the 404 and restore the doc chain.
---
Duplicate comments:
In `@docs/drive/model.md`:
- Around line 7-27: The fenced code block that begins with "Sized units
(smallest → largest):" should include a markdown language identifier to satisfy
linting (e.g., change the opening ``` to ```text or ```txt); update the opening
fence in docs/drive/model.md for that block so the markdown linter recognizes it
as a text/code block.
In `@docs/drive/principles/decomposition-and-cost.md`:
- Line 38: Replace the nonstandard word "revertable" in the sentence that starts
with "**Bounded recovery cost.**" (the phrase ending "...is trivially
revertable.") with a standard term such as "reversible" (or "revertible") so the
line reads "...is trivially reversible." to improve clarity and consistency in
user-facing wording.
In `@docs/drive/principles/gradual-ai-adoption.md`:
- Around line 7-15: The fenced code block that contains the spectrum table
starting with "Zero AI Full
delegation" is unlabeled and triggers MD040; update the opening fence from ```
to ```text (i.e., add the "text" language tag) while keeping the closing fence
unchanged so the block is properly labeled for the linter.
In `@docs/drive/principles/protocol-as-memory.md`:
- Around line 7-28: The fenced code block showing the repo tree is unlabeled
which triggers markdown lint MD040; update the opening fence from ``` to ```text
(i.e., change the unlabeled ``` that precedes the "your-repo/" tree in
protocol-as-memory.md to ```text) so the block is explicitly labeled as text and
the linter warning is resolved.
In `@docs/drive/principles/retro.md`:
- Around line 95-96: The durable principles doc currently prescribes a transient
project path by name ("projects/<x>/retros/<date>.md"); remove or reword that
explicit path so the document does not normalize project-specific transient
locations as a durable landing surface — replace the sentence referencing
"projects/<x>/retros/<date>.md" with guidance that retros may be drafted in
project-local (transient) locations but durable principles must not reference or
rely on those transient paths, and instead point readers to use the repository's
canonical/canonicalized retros or durable documentation locations per the "do
not reference transient project artifacts" policy.
In `@drive/pr/README.md`:
- Around line 15-17: Resolve the conflicting PR title rules by choosing the
conventional-commit convention and removing the alternate `<tml-id>:` prefix
rule; update the README so that the earlier rule "Conventional-commit prefix:
`feat:` / `fix:` / `chore:` / `docs:` / `refactor:` / `test:` / `build:` /
`ci:`" is the single canonical requirement and remove or replace the `<tml-id>:`
reference (and any text that reintroduces it) so both sections consistently
require a conventional-commit prefix plus the Linear ticket as either a
`(TML-NNNN)` suffix or `Refs: TML-NNNN` in the description.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: b380715d-a919-4b01-9336-87c6dd8d61eb
📒 Files selected for processing (26)
docs/drive/README.mddocs/drive/model.mddocs/drive/principles/brief-discipline.mddocs/drive/principles/decomposition-and-cost.mddocs/drive/principles/definition-of-done.mddocs/drive/principles/definition-of-ready.mddocs/drive/principles/gradual-ai-adoption.mddocs/drive/principles/protocol-as-memory.mddocs/drive/principles/retro.mddocs/drive/workflow.mddrive/README.mddrive/calibration/README.mddrive/calibration/dod.mddrive/calibration/dor.mddrive/calibration/failure-modes.mddrive/calibration/grep-library.mddrive/calibration/model-tier.mddrive/calibration/patterns.mddrive/calibration/sizing.mddrive/plan/README.mddrive/pr/README.mddrive/project/README.mddrive/qa/README.mddrive/retro/README.mddrive/spec/README.mdskills-contrib/drive-close-project/SKILL.md
✅ Files skipped from review due to trivial changes (7)
- drive/calibration/sizing.md
- drive/calibration/dor.md
- drive/spec/README.md
- drive/calibration/patterns.md
- drive/plan/README.md
- drive/calibration/model-tier.md
- docs/drive/README.md
wmadden
added a commit
that referenced
this pull request
May 19, 2026
Per PR #533 review comments 3264049516 + 3264049883: project-specific review knowledge belongs in `drive/<workflow>/README.md` (convention introduced on #522), not in generic `skills-contrib/drive-*/SKILL.md` bodies. - Revert the "Smells to surface during the principal-engineer pass" section added to `skills-contrib/drive-code-review/SKILL.md` and `skills-contrib/drive-pr-local-review/SKILL.md`. - Create `drive/code/README.md` (missing category README) carrying the `as Contract` smell entry, structured like `drive/qa/README.md`. #522 (which introduces the `drive/<workflow>/README.md` convention) can land independently — no conflict. Signed-off-by: Will Madden <madden@prisma.io>
wmadden
added a commit
that referenced
this pull request
May 19, 2026
Per PR #533 review comments 3264049516 + 3264049883: project-specific review knowledge belongs in `drive/<workflow>/README.md` (convention introduced on #522), not in generic `skills-contrib/drive-*/SKILL.md` bodies. - Revert the "Smells to surface during the principal-engineer pass" section added to `skills-contrib/drive-code-review/SKILL.md` and `skills-contrib/drive-pr-local-review/SKILL.md`. - Create `drive/code/README.md` (missing category README) carrying the `as Contract` smell entry, structured like `drive/qa/README.md`. #522 (which introduces the `drive/<workflow>/README.md` convention) can land independently — no conflict. Signed-off-by: Will Madden <madden@prisma.io>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/drive/model.md`:
- Line 402: Update the "Review artefacts" row in docs/drive/model.md to match
the current drive-build-workflow: replace the listed per-round artifacts
`system-design-review` and `walkthrough` with only `code-review.md` (i.e.,
change the cell to reference `projects/<project>/reviews/code-review.md` per
drive-build-workflow) and update the accompanying text to state that
code-review.md is the sole per-round review artifact; ensure references to
`drive-build-workflow` remain correct and remove mentions of the now-obsolete
`system-design-review` and `walkthrough`.
In `@skills-contrib/drive-build-workflow/SKILL.md`:
- Around line 370-373: The docs currently split the slice-plan path between
"projects/{project}/plans/plan.md" (in the plans tree) and
"projects/{project}/slices/<slice>/plan.md" (earlier sections); unify this
contract by choosing one canonical path and updating all references accordingly
— for example, replace the plans/plan.md mention with the per-slice path
projects/{project}/slices/<slice>/plan.md (or vice‑versa if you prefer global
plans), and adjust the spec.md and any occurrences referenced in the file to
match the chosen canonical path so artifacts are routed consistently during
execution (search for "plans/plan.md", "slices/<slice>/plan.md", "plan.md" and
update them to the single agreed path).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 821ea0f7-4bd3-46ea-8d14-8ce6a9ee25fb
📒 Files selected for processing (8)
docs/drive/model.mddocs/drive/principles/decomposition-and-cost.mddocs/drive/principles/gradual-ai-adoption.mddocs/drive/principles/protocol-as-memory.mddocs/drive/principles/retro.mddrive/pr/README.mdskills-contrib/drive-build-workflow/SKILL.mdskills-contrib/drive-close-project/SKILL.md
✅ Files skipped from review due to trivial changes (2)
- docs/drive/principles/decomposition-and-cost.md
- drive/pr/README.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/drive/principles/gradual-ai-adoption.md
Names Drive as a Kanban-shaped process with selected Scrum, XP, and SBE rituals layered on, and maps every lifecycle phase to its Agile parallel, the skill that owns it, the cadence, the role wearing it, and what gates it. The map is the spine for the rest of the project: DoR / DoD / brief discipline / retro / role docs and the new + augmented skills all plug into a phase named here. Signed-off-by: Will Madden <madden@prisma.io>
Merges projects/agile-agent-orchestration/ into projects/drive-domain-model/
and absorbs the sibling drive-domain-model project's snapshot (model.md
and spec.md, both formerly under reference/).
- Renames the folder agile-agent-orchestration → drive-domain-model.
- Promotes the sibling project's model.md to top-level (vocabulary source of
truth going forward).
- Stashes both predecessors' specs as spec.legacy-{methodology,sibling}.md
for absorption into a unified spec in a subsequent commit.
- Deletes both predecessors' HANDOVER.md (this conversation supersedes them).
- Gitignores reference/ clones (e.g. ignite) — local-only browsing aids.
The two projects had converged on the same target (Drive's domain model +
the dispatch-level discipline that operates on its units). This commit
brings them under one home; subsequent commits revise content (model.md
vocabulary refresh, unified spec/plan, new principle docs, calibration
refresh, skill restructuring plan).
Signed-off-by: Will Madden <madden@prisma.io>
…ll triage outputs Threads the agile-methodology project's decisions into the domain model so subsequent docs (workflow, spec, principles, calibration, skill restructure) build on a single substrate. Substantive changes: - Adds Dispatch as the unit of delegation to agent sessions (per the user's call: dispatch is the real-world unit; step is reserved for the implementer-internal logical-increment notion). The Planning context now owns Dispatch + Brief; Step retires to the Execution context (below the Drive-care line). - Adds Direct change as a sibling unit to Slice — the path triage takes for trivial work (copy changes, config flips, one-line fixes). One PR, intent in the PR body, no spec / no plan / no dispatch ceremony. - Adds Design discussion as a cross-cutting workflow (operator + agile orchestrator), fired by pre-spec, mid-spec, mid-flight on falsified-assumption, mid-flight on obstacle, or explicit request. Output: spec/plan edits + design-decisions.md entry. Backed by the existing drive-discussion mode skill, promoted here to first-class. - Expands Triage with the full output set (eight verdicts including Promote / Demote / Spike-first / Defer) and a mid-flight variant for scope re-evaluation in both directions (expansion and contraction). - Articulates sizing discipline at two scopes (new invariant I11): PR-cap at the slice/direct-change scope (triage enforces), M-cap at the dispatch scope (slice planning enforces; slice execution refuses L/XL in defense in depth). - Forbids silent agent-side spec/plan amendments after the first dispatch starts (new invariant I12) — amendments must be the output of a design discussion or an operator-authorised edit. - Specifies the Linear promotion pattern (Pattern 2 with the user's variant: move ticket into new Linear Project, mark Done, rename to "Plan: <project>" or comment) and adds the symmetric demotion pattern for collapsing a project back to slice / direct change. - Updates the canonical-skill-implications table: drive-create-spec and drive-create-plan split into project / slice variants per the user's call; introduces drive-triage-work, drive-health-check, drive-retro-run; promotes drive-discussion to a first-class cross-cutting skill. - Closes resolved open questions (OQ1 / OQ5 / OQ6 / OQ10) with rationale preserved in the historical trail; opens new ones around demotion authorisation and silent-amendment enforcement. Replaces the snapshot promoted from the sibling reference/ in the previous commit. Companion docs (workflow, spec, principles, calibration, skill-restructure) get aligned in subsequent commits. Signed-off-by: Will Madden <madden@prisma.io>
Add text fences, correct ASCII diagram skill names, and replace projects/ links with drive/triage, drive/plan, and drive/README durable targets. Signed-off-by: Will Madden <madden@prisma.io>
Signed-off-by: Will Madden <madden@prisma.io>
…-workflow rule Authors the missing close-out skill that every other Drive skill already references. Bakes in DoD verification (incl. mandatory final retro per invariant I10), file classification (long-lived methodology vs transient project artefacts), migration into docs/, repo-wide reference-strip, and the close-out PR. Hard gates protect against the two known close-out failure modes: - Operator confirmation required before any file deletion (defaults are heuristics, never authority). - Refuses if the final retro is missing. Retires the close-out section that used to live in the drive-project-workflow rule -- the skill body is now the source of truth for close-out methodology; the rule references it. Augments drive/project/README.md with close-out destination defaults and a PDoD addendum requiring an ADR audit at final retro. Wires the trial-period pointer in drive/project/README.md (findings file to follow in a subsequent slice). Signed-off-by: Will Madden <madden@prisma.io>
…-update-skills from ignite #93 Brings in the three mechanism skills that operationalise the drive/ context convention. Aligned to our skill conventions (frontmatter format with multi-line description + metadata.version; cross-reference paths; naming per D28). The substantive divergence from ignite is the new "Canonical-source resolution" section in each skill, which makes the trial-period story explicit: - During the prisma-next trial period (until first upstream PR to ignite), no external canonical exists. reconcile + update refuse with a pointer at the resolution table; bootstrap operates as normal (reads templates from this skill's local sibling). - Post-upstream, canonical = ignite (consumers fetch via npx skills). - Consumer projects that pull from prisma-next get a third "canonical = prisma-next/skills-contrib" entry. Templates ship with the bootstrap skill: 8 from ignite + 3 added for categories we seeded that ignite hasn't (triage, retro, health). The new templates mirror the structure of the existing seeded READMEs as placeholder skeletons. Signed-off-by: Will Madden <madden@prisma.io>
Adds the trial framing + recording protocol at docs/drive/trial.md (single source of truth: quality bar, tags, format, synthesis pointer). Wires drive/<category>/findings.md skeletons in all 8 seeded categories (health, plan, pr, project, qa, retro, spec, triage). Each is an initially-empty log that the trial period populates per the protocol. Adds an identical pointer block to each drive/<category>/README.md so agents loading any project-context README see the trial is on, know where to record findings, and know where to find the quality bar. Quality bar (per docs/drive/trial.md): - Action-worthy by a maintainer, OR - Repeatable friction the next operator will hit, OR - First-use of a skill / skill combination (baseline calibration). Skip routine successful runs, one-off operator errors, duplicates. Tags: friction, gap, win, surprise, boundary. Format: one short stanza per finding; suggested-action + upstream- candidate flags are optional but recommended. End-of-trial synthesis fires on or after 2026-06-02 via a Linear ticket (filed in a subsequent slice) that reads every findings.md and produces a consolidated report at wip/drive-trial-report.md. Signed-off-by: Will Madden <madden@prisma.io>
TML-2567 was filed in Linear as the end-of-trial synthesis ticket. Stamps the ID into docs/drive/trial.md so the trial framing doc points at the canonical place an agent will pick up the synthesis work on or after 2026-06-02. Ticket: https://linear.app/prisma-company/issue/TML-2567/ Signed-off-by: Will Madden <madden@prisma.io>
Required by drive-close-project step 2 before close-out can proceed. Captures the shaping + build phase only (project-start through this commit). Trial-period validation and upstream-PR prep are explicitly out of scope -- TML-2567 (the trial synthesis ticket) is where those lessons land. Lessons landed in surfaces: - Slicing the build into thematic commits (lesson for drive/plan/) - Build-locally-first pivot (already encoded in principles/gradual-ai-adoption.md) - D28 verb-noun atomic naming (lesson for drive/spec/) - .cursor/rules symlink + DCO trailer foot-guns (lessons for drive/pr/) The retros.md file itself is transient -- it lives in the project directory and will be deleted at step 8 of the close-out workflow. The lessons live in the surfaces above (or will, as the trial findings accrete and the synthesis ticket consolidates them). Signed-off-by: Will Madden <madden@prisma.io>
…n-model/ to docs/drive/ drive-close-project step 6 migration. Long-lived methodology files preserved at their new permanent home; transient project scaffolding (spec, plan, design-decisions, README, retros, calibration dir) stays in projects/drive-domain-model/ for step 8 deletion. Migration mapping (git mv preserves history): projects/drive-domain-model/model.md -> docs/drive/model.md projects/drive-domain-model/workflow.md -> docs/drive/workflow.md projects/drive-domain-model/problem-statement.md -> docs/drive/problem-statement.md projects/drive-domain-model/skill-restructure.md -> docs/drive/skill-conventions.md (renamed per default rule) projects/drive-domain-model/calibration/prisma-next.md -> docs/drive/calibration/prisma-next.md projects/drive-domain-model/principles/*.md (9 files) -> docs/drive/principles/*.md New docs/drive/README.md serves as the entry-point index for the migrated material with a reading guide by audience. Cross-references in skill bodies (drive-specify-slice, drive-create-spec, drive-create-plan) still point at the old projects/ paths -- those get re-pointed in the next slice (step 7: reference strip). Signed-off-by: Will Madden <madden@prisma.io>
drive-close-project step 7: external-reference strip after migration. Cross-references re-pointed to their new homes: - skills-contrib/drive-specify-slice/SKILL.md: model.md, principles/*, design-decisions.md refs -> docs/drive/* equivalents (the design-decisions ref repoints to skill-conventions.md since the raw ledger is transient and doesn't survive close-out). - skills-contrib/drive-create-spec/SKILL.md: design-decisions.md ref -> docs/drive/skill-conventions.md (where the split rationale lives as durable methodology). - skills-contrib/drive-create-plan/SKILL.md: same as above; also drops "(D9 + D24)" decision-ID inline citation since those IDs are about to disappear with the ledger. Migrated-doc cross-references within docs/drive/: - skill-restructure.md -> skill-conventions.md (rename) throughout. - spec.md / plan.md / design-decisions.md references either re-framed as inline prose or repointed at PR #522 (the close-out PR carries the project's commit history, which preserves the decision log). - New trial.md cross-references added where the migration removed references to plan.md's "build-then-trial-then-upstream" sequencing. .gitignore: the projects/drive-domain-model/reference/ exclusion generalised to projects/*/reference/ so future projects can opt into the same "browse local clones, don't commit" convention without gitignore touches. Re-scan returns clean (one false positive remains in calibration prose where the project's history references a 2026-05-17 agent-deletion incident; war-story text, not a link). Signed-off-by: Will Madden <madden@prisma.io>
drive-close-project step 8: deletion. Long-lived methodology lives at docs/drive/; the transient project scaffolding (spec, plan, README, design-decisions, retros) was retired by this commit. What's deleted: - spec.md (shaping artefact; acceptance criteria verified at step 2 -- AC1-AC7, AC17 met; AC8-AC18 deferred to TML-2567 by design). - plan.md (coordination artefact; execution complete). - README.md (project orientation; superseded by docs/drive/README.md). - design-decisions.md (chronological alternatives ledger; the durable rationale was either inlined into the migrated docs or remains in the PR #522 commit history for archeology). - retros.md (mandatory-final retro entry; lessons landed in the surfaces accounted for in the retro itself per invariant I10). What's preserved (already migrated at step 6): - docs/drive/principles/*.md (9 principle docs) - docs/drive/model.md, workflow.md, problem-statement.md - docs/drive/skill-conventions.md (renamed from skill-restructure.md) - docs/drive/calibration/prisma-next.md - docs/drive/trial.md (trial framing for the validation window) - docs/drive/README.md (entry-point index for the migrated material) Linked issue: TML-2549. Linked synthesis ticket: TML-2567. Signed-off-by: Will Madden <madden@prisma.io>
The ADR link used a path relative to the repo root, but the file lives at drive/retro/README.md so the link needs two levels up to reach docs/. Fixes the broken link reported in PR review thread PRRT_kwDOQM0QJc6DCy6B. Signed-off-by: Will Madden <madden@prisma.io>
The calibration content (reference tasks, DoR/DoD overlays, failure-mode catalogue, grep library, model-tier routing, Linear ceremony, manual-QA context) is project-specific by definition -- it belongs where the skills actually load it (drive/<category>/README.md), not as long-lived docs under docs/drive/. This commit dogfoods the drive-close-project rule that surfaces of value under calibration/** get lifted into project-context READMEs before deletion. The original docs/drive/calibration/prisma-next.md was a worked-example transitional doc with a section-by-section mapping table to the same destinations; this commit follows that mapping and deletes the source. Redistribution: - drive/plan/README.md: reference anchors (XS/S/M/L/XL), dispatch-DoR overlay, dispatch-DoD gates (always-run + conditional + cadence + additional items), failure-mode catalogue (F1-F5), grep library (IR substrate / test-literal / cross-cutting), model-tier routing. - drive/project/README.md: Linear conventions, project-DoR overlay, expanded project-DoD overlay (repo-wide gates + doc/migration + Linear close-out + manual-QA roll-up). - drive/spec/README.md: slice-DoR overlay (issue + parent-branch). - drive/pr/README.md: Linear-issue conventions (title prefix, Refs: line), Linear state conventions (Ready to be merged), slice-DoD PR-side items. - drive/qa/README.md: replaced placeholder CLI/agent audiences with the real Extension authors / End users audiences; rewrote substrate locations, coverage-gate gaps, and slice-DoD QA-side items from the calibration source; stripped the stale calibration cross-ref. - drive/README.md: refreshed category map (added qa/, expanded plan/ and project/ descriptions; the descriptions are now accurate). Reference fixes: - docs/drive/README.md: replaced the "worked example" link entry with prose explaining that calibration is project-context and lives at drive/<category>/README.md. - docs/drive/problem-statement.md: same. - docs/drive/model.md: re-pointed both calibration cross-refs to drive/plan/README.md (anchors) and drive/ (overlays). Linked issue: TML-2549. Signed-off-by: Will Madden <madden@prisma.io>
…ions
Adds step 4.5 to drive-close-project (and the supporting pattern
catalogue + pitfalls) so close-out catches files whose content is
methodology but whose voice is project-shaping -- the failure mode
that produced our own close-outs cruft.
The trial-period finding under drive/project/findings.md records the
specific gap surfaced by closing out drive-domain-model:
- problem-statement.md migrated as long-lived (it was a proposal
letter to canonical maintainers).
- skill-conventions.md migrated as long-lived (it was titled "Skill
restructuring plan" and described what we changed, not the
resulting conventions).
- workflow.md migrated with "Bold = new (this project adds it)"
framing baked in -- meaningless to a fresh reader.
- definition-of-ready.md and definition-of-done.md migrated with
"Worked example for prisma-next:" sections that duplicate
overlays already lifted into drive/<category>/README.md.
- trial.md migrated as long-lived despite documenting a specific
2026-05-19 -> 2026-06-02 window.
What the skill update adds:
1. Step 4.5 -- prose audit on every long-lived candidate. Four smell
tests: project-shaping voice in headings / prose; status blocks
tied to project lifecycle; worked-example pollution duplicating
project-context; worked examples anchored to specific real-world
incidents. Each match yields a per-file disposition: rewrite-at-
migration, lift-example-to-context, soften-at-migration, or
reclassify-as-transient.
2. Step 5 confirmation extended to cover the disposition (the
operator signs off on the disposition, not just the
classification).
3. Step 6 migration extended to apply dispositions
(rewrite / lift / soften instead of bare git mv where the audit
matched).
4. Default classification table extended:
- *-restructure.md / migration-plan.md / *-changes.md -> transient
(execution plans describing project deltas).
- problem-statement.md / pitch.md / proposal.md / motivation.md
-> transient (project-shaping / advocacy artefacts).
- trial.md / validation.md / rollout.md -> transient
(time-windowed execution artefacts).
- principles/**, model.md, workflow.md, *-conventions.md flagged
"long-lived (prose-audit at step 4.5)" -- still long-lived by
default, audit catches the exceptions.
5. Three new pitfalls (#8, #9, #10) covering the three audit-caught
failure modes.
6. Checklist updated to require dispositions recorded + operator
confirmation covering them.
Slices A + B (separate commits) apply the audit to the existing
docs/drive/ tree and clear the cruft this same finding surfaced.
Linked issue: TML-2549. Trial-period finding contributes to TML-2567
upstream-PR synthesis.
Signed-off-by: Will Madden <madden@prisma.io>
Applies the prose audit from drive-close-project (per the
trial-period finding under drive/project/findings.md) to the
docs/drive/ tree. This is the cleanup half of the follow-up;
the rewrite half (workflow.md / model.md / worked examples) lands as
a separate slice.
Files removed (reclassified-as-transient):
- docs/drive/problem-statement.md -- a proposal letter to canonical
maintainers ("What we kept going wrong / What we are proposing /
What we would like from you"). Project-shaping artefact; PR #522
description preserves the narrative for anyone who needs it.
- docs/drive/skill-conventions.md -- titled "Skill restructuring
plan", with "What changes from current to final", "Build
sequencing", "Upstream promotion (later)". Project execution plan;
the resulting state lives in model.md / workflow.md / the
skill bodies themselves.
Content lifted into model.md before deletion:
- The naming convention from skill-conventions.md is now in
docs/drive/model.md as a new "Naming convention" subsection under
"Two skill tiers: workflow and atomic" -- the only piece of
enduring methodology buried in the restructuring plan.
File moved (reclassified as project context):
- docs/drive/trial.md -> drive/trial.md. The 2026-05-19 -> 2026-06-02
trial window is project-execution context tied to TML-2567, not
enduring methodology. Pointer blocks in all 8 drive/<category>/
READMEs + 8 findings.md files re-pointed at ../trial.md.
Worked-example sections lifted into project context (per the
calibration/** rule):
- docs/drive/principles/definition-of-ready.md "Worked example for
prisma-next:" block -- the content (Project / Slice / Dispatch
DoR overlays) already lives in drive/project/README.md,
drive/spec/README.md, drive/plan/README.md after the calibration
redistribution. Replaced with a one-line pointer at ../../drive/.
- docs/drive/principles/definition-of-done.md "Worked example for
prisma-next:" block -- same. Content already in drive/project/,
drive/pr/, drive/qa/, drive/plan/ READMEs. Replaced with pointer.
External references re-pointed:
- skills-contrib/drive-create-plan / drive-create-spec /
drive-specify-slice SKILL.md bodies: refs to skill-conventions.md
-> model.md § Two skill tiers.
- docs/drive/principles/gradual-ai-adoption.md ref to
skill-conventions.md -> model.md anchor.
- docs/drive/workflow.md ref to skill-conventions.md -> skills-contrib/
+ model.md naming-convention anchor.
- docs/drive/model.md three references re-pointed or removed.
- docs/drive/README.md trimmed: reading guide drops problem-statement,
drops the skill-conventions entry; trial entry re-pointed at
drive/trial.md and re-framed as project context; status footer
trimmed (was tied to the trial); migration-history footer dropped
(project-historical).
Linked issue: TML-2549. Linked finding: drive/project/findings.md
2026-05-19. Trial-period contribution to TML-2567 upstream synthesis.
Signed-off-by: Will Madden <madden@prisma.io>
…oice
Slice B applies the rewrite-at-migration and soften-at-migration
dispositions from drive-close-project step 4.5 to the docs/drive/
files that survived Slice A. Each file kept its methodology core
and lost its project-execution framing.
workflow.md -- rewrite-at-migration:
- Drops the "Bold = new (this project adds it); plain = exists today;
italic = augmented" legend from the lifecycle table header. Bold
treatment removed from every row; reads as steady-state methodology.
- Skill-surface section rewritten: was a "what changed" inventory
organised as new / split / augmented / promoted; now an
organised-by-purpose list of the canonical drive-* skill set.
Both tiers (workflow + atomic) covered without the change-tracking
framing.
- Reading guide drops the "what is new versus existing" link.
- "Status: living document; updates here are load-bearing for every
other doc in this project" footer dropped.
model.md -- rewrite-at-migration + soften-at-migration:
- "Implications for existing canonical Drive" + "Atomic skills that
split / stay / new" subsections (project-restructure framing)
rewritten as a single "Skill set" section: Workflow skills table
+ Atomic skills table organised by purpose. No "new vs existing,"
no "splits into," no "renamed from."
- "Open questions" block dropped (it was a closed-questions trail
from project shaping -- OQ1/OQ5/OQ6/OQ10 -- with no methodology
role going forward; the questions are resolved by the model itself).
- "Linear sync" section generalised to "Tracker sync" using generic
tracker vocabulary (tracker project / tracker issue / etc.) with
Linear / Jira / GitHub Issues listed as worked examples in the
bounded-contexts diagram. MCP tool names (save_project,
update_issue) replaced with generic verbs ("create a tracker
project", "move the ticket"). Tracker-specific concretes belong
in project context (drive/project/, drive/triage/, drive/pr/).
- At-a-glance summary + bounded-contexts diagram + Triage section
+ Aggregate-roots section + Triage decision tree all updated to
say "tracker" rather than "Linear" where the reference is to the
abstract concept; Linear remains as a named worked example.
- Persistence-shape table drops the inline PR #93 attributions on
Manual-QA + project-context rows (the skill is now first-class;
its own SKILL.md is the source).
principles/brief-discipline.md, definition-of-ready.md,
definition-of-done.md -- soften-at-migration:
- Replaces StorageTable / flat-shape / packages/2-sql / 2026-05-17
anchors with generic "legacy-shape" + "data-shape migration" +
"<date>" placeholders. The example shape (three-round migration,
spike-then-implement, programmatic-grep-route-around catch) is
preserved; the project-specific names are not.
principles/decomposition-and-cost.md -- soften-at-migration:
- Two t-shirt-sizing table rows had StorageTable / ForeignKeyReference
as worked examples; generalised to "substrate type that affects
every IR consumer" / "two adjacent substrate types" without losing
the sizing intuition.
principles/retro.md -- soften-at-migration:
- The "retro that actually happened" example is preserved in shape
(dispatch-failure retro, intent-validation catch, programmatic-grep
route-around, output lands in drive/plan/README.md) but the
specific date, the StorageTable name, the Object.fromEntries
constructor, and the "prisma-next-specific" attribution are
generalised away. Reads as a representative retro a fresh team
can follow.
principles/protocol-as-memory.md, retro.md, spikes.md --
non-portable-conventions cleanup:
- References to the wip/ convention replaced with "operator scratch
(untracked working notes, draft files outside the tracked tree)".
The concept (no-memory surface for transient scratch) is preserved;
the prisma-next-specific wip/ path is not.
skills-contrib/drive-start-workflow/SKILL.md -- mechanical:
- Two section references that pointed at model.md § Linear sync
re-pointed at model.md § Tracker sync to match the rename.
Linked issue: TML-2549. Linked finding: drive/project/findings.md
2026-05-19.
Signed-off-by: Will Madden <madden@prisma.io>
Calibration content (sizing anchors, DoR/DoD overlays, failure-mode catalogue, grep library, model-tier routing, accreted patterns) was smeared across drive/<category>/README.md, which made the most important and most-referenced project context the hardest to find. A single failure mode often informed multiple categories overlays in different files, with no canonical home. Centralize into drive/calibration/ as eight focused files (README, sizing, model-tier, dor, dod, failure-modes, grep-library, patterns). Each category README now retains its operational conventions and links to the relevant calibration files. Update docs/drive/ principle docs to describe the project-context surface generically (the team chooses centralised vs per-category layout). Update drive-close-project (skill v2026.5.19.2) so the calibration/** lift rule names both layouts. Signed-off-by: Will Madden <madden@prisma.io>
…ncy) - Add `text` language tag to fenced blocks in model.md, gradual-ai-adoption.md, protocol-as-memory.md, and drive-close-project SKILL.md (MD040 lint fixes) - Fix typo: revertable → reversible in decomposition-and-cost.md - Fix skill name: drive-review-code → drive-code-review in protocol-as-memory.md - Remove transient projects/<x>/ path reference from durable retro.md principle - Add Cancelled-with-rationale to Step 2 AC state model in drive-close-project - Update legacy drive-create-spec / drive-create-plan refs in drive-build-workflow to drive-specify-slice / drive-plan-slice - Unify PR title convention in drive/pr/README.md: drop conflicting <tml-id>: prefix rule, align Linear-issue section with conventional-commit convention Signed-off-by: Will Madden <madden@prisma.io>
…d-workflow
- docs/drive/model.md: trim review-artefacts row to just code-review.md, matching
drive-build-workflow § The artifact contract (system-design-review and
walkthrough are no longer per-round artifacts)
- skills-contrib/drive-build-workflow/SKILL.md: move spec.md and plan.md under
projects/{project}/slices/<slice>/ in the artifact map so the contract matches
the slice-plan paths used elsewhere in this skill (lines 43, 107, 538)
Signed-off-by: Will Madden <madden@prisma.io>
wmadden
force-pushed
the
tml-2549-agile-agent-orchestration
branch
from
bef8e3e to
e8d57c8
Compare
The rule has been fully superseded by the drive-* skill cluster and the methodology docs under docs/drive/: - shaping workflow -> drive-start-workflow + drive-specify-project + drive-plan-project (the rule still referenced the renamed drive-create-spec / drive-create-plan names) - project lifecycle -> docs/drive/workflow.md - artifact layout -> drive-create-project skill body - close-out -> drive-close-project skill body - tracker conventions -> drive/project/README.md + drive/pr/README.md Keeping it added duplicate always-applied context that referenced non-existent skills. Delete both copies (.agents/rules/ + .cursor/rules/), re-point the AGENTS.md and projects/README.md pointers at the drive workflow skills + docs/drive/, and update the drive-create-plan + drive-close-project skill bodies that referenced the rule by name. Signed-off-by: Will Madden <madden@prisma.io>
wmadden
added a commit
that referenced
this pull request
May 19, 2026
drive-close-project step 7: external-reference strip after migration. Cross-references re-pointed to their new homes: - skills-contrib/drive-specify-slice/SKILL.md: model.md, principles/*, design-decisions.md refs -> docs/drive/* equivalents (the design-decisions ref repoints to skill-conventions.md since the raw ledger is transient and doesn't survive close-out). - skills-contrib/drive-create-spec/SKILL.md: design-decisions.md ref -> docs/drive/skill-conventions.md (where the split rationale lives as durable methodology). - skills-contrib/drive-create-plan/SKILL.md: same as above; also drops "(D9 + D24)" decision-ID inline citation since those IDs are about to disappear with the ledger. Migrated-doc cross-references within docs/drive/: - skill-restructure.md -> skill-conventions.md (rename) throughout. - spec.md / plan.md / design-decisions.md references either re-framed as inline prose or repointed at PR #522 (the close-out PR carries the project's commit history, which preserves the decision log). - New trial.md cross-references added where the migration removed references to plan.md's "build-then-trial-then-upstream" sequencing. .gitignore: the projects/drive-domain-model/reference/ exclusion generalised to projects/*/reference/ so future projects can opt into the same "browse local clones, don't commit" convention without gitignore touches. Re-scan returns clean (one false positive remains in calibration prose where the project's history references a 2026-05-17 agent-deletion incident; war-story text, not a link). Signed-off-by: Will Madden <madden@prisma.io>
wmadden
added a commit
that referenced
this pull request
May 19, 2026
drive-close-project step 8: deletion. Long-lived methodology lives at docs/drive/; the transient project scaffolding (spec, plan, README, design-decisions, retros) was retired by this commit. What's deleted: - spec.md (shaping artefact; acceptance criteria verified at step 2 -- AC1-AC7, AC17 met; AC8-AC18 deferred to TML-2567 by design). - plan.md (coordination artefact; execution complete). - README.md (project orientation; superseded by docs/drive/README.md). - design-decisions.md (chronological alternatives ledger; the durable rationale was either inlined into the migrated docs or remains in the PR #522 commit history for archeology). - retros.md (mandatory-final retro entry; lessons landed in the surfaces accounted for in the retro itself per invariant I10). What's preserved (already migrated at step 6): - docs/drive/principles/*.md (9 principle docs) - docs/drive/model.md, workflow.md, problem-statement.md - docs/drive/skill-conventions.md (renamed from skill-restructure.md) - docs/drive/calibration/prisma-next.md - docs/drive/trial.md (trial framing for the validation window) - docs/drive/README.md (entry-point index for the migrated material) Linked issue: TML-2549. Linked synthesis ticket: TML-2567. Signed-off-by: Will Madden <madden@prisma.io>
wmadden
added a commit
that referenced
this pull request
May 19, 2026
Applies the prose audit from drive-close-project (per the
trial-period finding under drive/project/findings.md) to the
docs/drive/ tree. This is the cleanup half of the follow-up;
the rewrite half (workflow.md / model.md / worked examples) lands as
a separate slice.
Files removed (reclassified-as-transient):
- docs/drive/problem-statement.md -- a proposal letter to canonical
maintainers ("What we kept going wrong / What we are proposing /
What we would like from you"). Project-shaping artefact; PR #522
description preserves the narrative for anyone who needs it.
- docs/drive/skill-conventions.md -- titled "Skill restructuring
plan", with "What changes from current to final", "Build
sequencing", "Upstream promotion (later)". Project execution plan;
the resulting state lives in model.md / workflow.md / the
skill bodies themselves.
Content lifted into model.md before deletion:
- The naming convention from skill-conventions.md is now in
docs/drive/model.md as a new "Naming convention" subsection under
"Two skill tiers: workflow and atomic" -- the only piece of
enduring methodology buried in the restructuring plan.
File moved (reclassified as project context):
- docs/drive/trial.md -> drive/trial.md. The 2026-05-19 -> 2026-06-02
trial window is project-execution context tied to TML-2567, not
enduring methodology. Pointer blocks in all 8 drive/<category>/
READMEs + 8 findings.md files re-pointed at ../trial.md.
Worked-example sections lifted into project context (per the
calibration/** rule):
- docs/drive/principles/definition-of-ready.md "Worked example for
prisma-next:" block -- the content (Project / Slice / Dispatch
DoR overlays) already lives in drive/project/README.md,
drive/spec/README.md, drive/plan/README.md after the calibration
redistribution. Replaced with a one-line pointer at ../../drive/.
- docs/drive/principles/definition-of-done.md "Worked example for
prisma-next:" block -- same. Content already in drive/project/,
drive/pr/, drive/qa/, drive/plan/ READMEs. Replaced with pointer.
External references re-pointed:
- skills-contrib/drive-create-plan / drive-create-spec /
drive-specify-slice SKILL.md bodies: refs to skill-conventions.md
-> model.md § Two skill tiers.
- docs/drive/principles/gradual-ai-adoption.md ref to
skill-conventions.md -> model.md anchor.
- docs/drive/workflow.md ref to skill-conventions.md -> skills-contrib/
+ model.md naming-convention anchor.
- docs/drive/model.md three references re-pointed or removed.
- docs/drive/README.md trimmed: reading guide drops problem-statement,
drops the skill-conventions entry; trial entry re-pointed at
drive/trial.md and re-framed as project context; status footer
trimmed (was tied to the trial); migration-history footer dropped
(project-historical).
Linked issue: TML-2549. Linked finding: drive/project/findings.md
2026-05-19. Trial-period contribution to TML-2567 upstream synthesis.
Signed-off-by: Will Madden <madden@prisma.io>
This was referenced May 20, 2026
This was referenced May 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
A single PR that ships the Drive methodology + skill set for prisma-next: shaping → build → close-out → trial instrumentation. Closes the
drive-domain-modelshaping project; long-lived methodology now lives atdocs/drive/; canonical skill bodies live atskills-contrib/drive-*/.Refs: TML-2549. Trial-period synthesis: TML-2567.
Why
Two failure modes kept biting us with the canonical
drive-*skills:drive-create-planproduces "a plan" that may be project-scope, task-scope, or anywhere between. The Linear-sync workflow sits on top of a floating "milestone" unit; prisma-next ended up deleting the parts it couldn't make sense of. A parallel canonical lives in our.agents/skills/that never flowed back.wip/unattended-decisions.mdfrom 2026-05-17 ontarget-extensible-ir— file-system-proxy monitoring missed a programmatic-grep route-around; CI passed; failure surfaced three slices later.These compound — unit confusion produces oversized work; the dispatch loop inherits it and runs unsupervised. The methodology in
docs/drive/and the skill set inskills-contrib/address both.What's shipping
Methodology (
docs/drive/):model.md— pinned domain model: 3 sized units (Direct change / Slice / Project) + Dispatch as delegation unit; 8 workflows; 12 invariants.workflow.md— operational lifecycle map; every skill plugs into a named phase.problem-statement.md— externally-shareable problem framing for ignite maintainers.skill-conventions.md— two-tier (workflow + atomic) skill architecture, naming rules (D28:drive-<verb>-<noun>).principles/— 9 principle docs: protocol-as-memory, decomposition-and-cost, brief-discipline, DoR, DoD, retro, spikes, roles-and-personas, gradual-ai-adoption.calibration/prisma-next.md— worked-example calibration showing whatdrive/<category>/README.mdoverlays look like.trial.md— trial-period framing + findings-recording protocol (2026-05-19 → 2026-06-02).Skill set (
skills-contrib/drive-*/):drive-start-workflow,drive-build-workflow,drive-deliver-workflow.drive-triage-work,drive-specify-project,drive-specify-slice,drive-plan-project,drive-plan-slice,drive-check-health,drive-run-retro.drive-close-project(new + bakes in the close-out methodology),drive-create-project(DoR check + context bootstrap),drive-discussion(promoted),drive-pr-description(direct-change mode).drive-bootstrap-context,drive-reconcile-skills,drive-update-skills— adapted with the trial-period canonical-source resolution note.drive-create-spec,drive-create-plan— point at their split replacements; will not ship upstream.Trial-period instrumentation:
docs/drive/trial.md— quality bar (action-worthy / repeatable-friction / first-use), tags (friction / gap / win / surprise / boundary), format.drive/<category>/findings.mdper category (8 files) — empty logs that the trial period populates.drive/<category>/README.mdso agents loading any project-context README see the trial is on.Project close-out (done by the new
drive-close-projectskill — first dogfood):projects/drive-domain-model/→docs/drive/(per the destination defaults indrive/project/README.md)..gitignorere-pointed atdocs/drive/.projects/drive-domain-model/deleted.How to read this PR
docs/drive/problem-statement.md.docs/drive/model.md.docs/drive/workflow.md.docs/drive/skill-conventions.md.skills-contrib/drive-<name>/SKILL.md.docs/drive/trial.md.Out of scope
prisma/ignite— that's TML-2567, fires after the trial completes.prisma-nextprojects to the new skill set — adopt on each project's own schedule.Summary by CodeRabbit
New Features
Documentation