Conversation
WalkthroughAdds comprehensive spec-driven development documentation and prompts: a master SKILL spec, command references (setup, new_project, continue, implement, code_review), step-by-step planning guides, sub-agent prompts for implementation and CR, pushback/spawning guidance, monorepo notes, and .specs_state ignored in .gitignore. Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant CLI as /spec CLI
participant Manager as Spec Manager
participant FS as Repo/Filesystem
participant Sub as Coding Sub-agent
participant CR as Code-Review Agent
User->>CLI: run /spec new_project or /spec continue or /spec implement
CLI->>Manager: route command, load .specs_skill_state/current_project.md
Manager->>FS: read/write specs/projects/PROJECT_NAME/* (frontmatter status)
Manager->>Sub: spawn sub-agent with phase prompt + project docs
Sub->>FS: create/modify files, run tests/lint, commit changes
Sub->>CR: request code review (spawn CR sub-agent) with patch + specs
CR->>Manager: return findings (Critical/Moderate/Mild)
Manager->>Sub: feed back review for fixes (iterate)
Sub->>FS: apply fixes, update implementation_plan.md
Manager->>User: present completion summary / next actions
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment Tip You can disable sequence diagrams in the walkthrough.Disable the |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new 'spec-driven development' skill designed to streamline the software development lifecycle. It provides a robust framework that guides users from initial project conception through detailed specification, phased implementation, and rigorous code review. By clearly defining roles for human decision-makers and AI agents, the skill aims to enhance project clarity, maintainability, and overall quality, ensuring that development aligns closely with well-defined specifications. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new "spec" skill for spec-driven development. It adds a comprehensive set of documentation files that define the process, commands, and agent prompts for planning, building, and reviewing projects. The changes are well-structured and the process is well-thought-out. I've found a few minor inconsistencies and errors in the documentation that should be addressed to improve clarity and correctness.
| - Mark `complete` after user confirmation | ||
| - If a completed artifact is edited, downstream artifacts cascade to `draft` (if they may be affected) | ||
|
|
||
| Dependency chain: `project_overview → functional_spec → architecture → components → implementation_plan` |
There was a problem hiding this comment.
The dependency chain described here is missing the ui_design step, which is mentioned in other parts of the documentation (e.g., cmd_continue.md and cmd_new_project.md) as a conditional step between functional_spec and architecture. To maintain consistency, it should be included here.
| Dependency chain: `project_overview → functional_spec → architecture → components → implementation_plan` | |
| Dependency chain: `project_overview → functional_spec → ui_design → architecture → components → implementation_plan` |
| - → Read [references/spawning_subagents.md](references/spawning_subagents.md) for how to spawn | ||
| - Pass: phase number, project path, instruction to follow single-phase implementation | ||
| 3. **Auto-commit**: `"Phase N implementation of [project name]\n\n[description of work in phase]"` | ||
| 4. Show the phase summary from the subagent to the user |
There was a problem hiding this comment.
There is a typo "subagent". For consistency with the rest of the documentation which uses "sub-agent", this should be corrected.
| 4. Show the phase summary from the subagent to the user | |
| 4. Show the phase summary from the sub-agent to the user |
| 4. Run tests. Iterate until passing. | ||
| 5. Run automated checks again. Iterate until clean. | ||
| 6. Self code-review via sub-agent: | ||
| - Read `spec/references/cr_agent_prompt.md` for the CR process |
There was a problem hiding this comment.
The path spec/references/cr_agent_prompt.md appears to be incorrect. Assuming the sub-agent runs from the repository root, the path should be .cursor/skills/specs/references/cr_agent_prompt.md to be valid.
| - Read `spec/references/cr_agent_prompt.md` for the CR process | |
| - Read `.cursor/skills/specs/references/cr_agent_prompt.md` for the CR process |
|
|
||
| ## CR Iteration Loop | ||
|
|
||
| 1. Spawn CR sub-agent with the CR prompt from `spec/references/cr_agent_prompt.md` |
There was a problem hiding this comment.
The path spec/references/cr_agent_prompt.md appears to be incorrect. Assuming the sub-agent runs from the repository root, the path should be .cursor/skills/specs/references/cr_agent_prompt.md to be valid.
| 1. Spawn CR sub-agent with the CR prompt from `spec/references/cr_agent_prompt.md` | |
| 1. Spawn CR sub-agent with the CR prompt from `.cursor/skills/specs/references/cr_agent_prompt.md` |
📊 Coverage ReportOverall Coverage: 91% Diff: origin/main...HEADNo lines with coverage information in this diff.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.cursor/skills/specs/references/cmd_code_review.md:
- Around line 34-38: The fenced example block beginning with the triple
backticks that contains the <prior_cr_feedback> element lacks a language tag;
update the opening fence (the ``` that starts the block) to include a language
identifier such as xml (e.g., change ``` to ```xml) so the block is properly
syntax-tagged and markdown lint warnings are resolved.
- Around line 20-23: The markdown contains incorrect sibling links like
"references/spawning_subagents.md" and "references/cr_agent_prompt.md" which
resolve to references/references/...; change them to sibling-relative paths
"./spawning_subagents.md" and "./cr_agent_prompt.md" (and update any other
occurrences of those same link strings elsewhere in the file, e.g., the
occurrences near the bottom that mirror lines 68-69) so the links point
correctly to the files in the same directory.
In @.cursor/skills/specs/references/cmd_continue.md:
- Around line 34-37: The fenced code block that currently contains the
dependency order list (the block showing "project_overview.md →
functional_spec.md → ui_design.md (if exists) → architecture.md → components/
(if exists) → implementation_plan.md") should have a language specified to
satisfy markdownlint; change the opening fence from ``` to ```text so the block
is marked as plain text and formatting/linting pass for the fence starting at
that dependency-order block.
In @.cursor/skills/specs/references/cmd_implement.md:
- Around line 65-67: The sibling links in cmd_implement.md incorrectly include
the leading "references/" prefix (e.g., "references/spawning_subagents.md" and
"references/cr_agent_prompt.md") even though the file already lives in the
references/ directory; update those link targets to be relative within the same
folder (remove the "references/" prefix) for all occurrences (including the ones
at lines ~101-102 and ~116-122) so links point to spawning_subagents.md,
cr_agent_prompt.md, etc.
- Line 54: The docs line currently references the repo-root location
`/phase_plans/phase_N.md`; change that wording in cmd_implement.md so it
instructs writers to place phase plans in the project-specific phase_plans
directory (i.e., the phase_plans folder under the target project), not the
repository root—replace the literal `/phase_plans/phase_N.md` with a
project-scoped placeholder that makes the intended project-local path clear.
In @.cursor/skills/specs/references/cmd_setup.md:
- Around line 104-118: The markdown block under the "### Suggested Addition:
Automated Checks" section uses nested triple-backtick fences which can render
incorrectly; change the outer fenced code block to a longer fence (e.g., four
backticks) or indent the inner block so the inner "```markdown" block is
preserved; update the outer fence where the example begins and ends so the
nested fenced block for "## Automated Code Checks" remains intact.
In @.cursor/skills/specs/references/coding_phase_prompt.md:
- Line 57: Replace the incorrect path prefix
"spec/references/cr_agent_prompt.md" (and any other occurrences using
"spec/references/...") in the coding sub-agent prompt to the repository's actual
reference path by updating the two occurrences (lines referencing
"spec/references/...") to "references/cr_agent_prompt.md" (i.e., change
"spec/references/..." → "references/...") so the CR loop instructions point to
the correct prompt file.
In @.cursor/skills/specs/references/cr_agent_prompt.md:
- Around line 94-98: The fenced code block containing the <prior_cr_feedback>
XML snippet is missing a language specifier; update the fenced block that starts
with ``` to include a language identifier such as text or xml (for example
change ``` to ```text or ```xml) so the block becomes fenced with a language and
satisfies markdown linting and improves rendering.
In @.cursor/skills/specs/references/spawning_subagents.md:
- Around line 29-31: The Claude Code example uses an incorrect prompt path
inside the Task(...) call; update the string
"spec/references/cr_agent_prompt.md" to the correct docs location used in this
repo (e.g., "specs/references/cr_agent_prompt.md") so the Task(...) reference
points to the actual prompt file; modify the Task invocation in the markdown
example accordingly.
In @.cursor/skills/specs/references/step_architecture.md:
- Line 91: The markdown link currently points to "references/pushback.md" which
is incorrect for this directory; update the link target on the arrowed line (the
line containing "→ Load [references/pushback.md](references/pushback.md) if not
already loaded.") to use a relative path to the local file (e.g., "pushback.md"
or "./pushback.md") so the link correctly resolves from this document's
directory.
In @.cursor/skills/specs/references/step_functional_spec.md:
- Line 81: The Markdown link uses a nested path "references/pushback.md" that
likely doesn't exist relative to step_functional_spec.md; update the link to the
correct relative path "pushback.md" (or "./pushback.md") so the reference
resolves correctly, i.e., replace references/pushback.md with pushback.md in the
document.
In @.cursor/skills/specs/references/step_ui_design.md:
- Line 57: Update the broken relative markdown link on the line containing "→
Load [references/pushback.md](references/pushback.md) if not already loaded." to
point directly to pushback.md (e.g., change the link target to pushback.md or
./pushback.md) so it no longer resolves to references/references/...; ensure the
visible text can remain "references/pushback.md" if desired but the URL target
must be corrected.
In @.cursor/skills/specs/SKILL.md:
- Around line 107-109: The fenced code block showing "Current Project:
/specs/projects/project_name" is unlabeled; update that triple-backtick fence to
specify the language tag `text` so the block becomes ```text — locate the code
block containing the string "Current Project: /specs/projects/project_name" in
SKILL.md and add the `text` tag to the opening fence for markdownlint
compatibility and consistency.
In `@specs/monorepo.md`:
- Line 9: The phrase "fine tuning" in the libs/core description should use a
hyphenated compound modifier; update the string in the monorepo spec (the table
row containing "`libs/core/` | Python library with the core functionality of
Kiln (evals, synthetic data gen, fine tuning, RAG, etc.)") to read "fine-tuning"
so the description becomes "evals, synthetic data gen, fine-tuning, RAG, etc."
to maintain consistent technical writing.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: d86724b3-dad9-422d-bae4-f8f9d5042942
📒 Files selected for processing (21)
.cursor/skills/specs/SKILL.md.cursor/skills/specs/references/cmd_code_review.md.cursor/skills/specs/references/cmd_continue.md.cursor/skills/specs/references/cmd_implement.md.cursor/skills/specs/references/cmd_new_project.md.cursor/skills/specs/references/cmd_setup.md.cursor/skills/specs/references/coding_phase_prompt.md.cursor/skills/specs/references/cr_agent_prompt.md.cursor/skills/specs/references/pushback.md.cursor/skills/specs/references/spawning_subagents.md.cursor/skills/specs/references/step_architecture.md.cursor/skills/specs/references/step_component_designs.md.cursor/skills/specs/references/step_functional_spec.md.cursor/skills/specs/references/step_ui_design.md.gitignoreapp/desktop/specs/projects/.gitkeepapp/web_ui/specs/projects/.gitkeeplibs/core/specs/projects/.gitkeeplibs/server/specs/projects/.gitkeepspecs/monorepo.mdspecs/projects/.gitkeep
| → Read [references/spawning_subagents.md](references/spawning_subagents.md) for how to spawn sub-agents. | ||
|
|
||
| Pass the prompt from [references/cr_agent_prompt.md](references/cr_agent_prompt.md), plus scope description. | ||
|
|
There was a problem hiding this comment.
Fix broken relative reference links in this file.
Because this file already lives in references/, links like references/spawning_subagents.md and references/cr_agent_prompt.md point to references/references/... and won’t resolve correctly. Use sibling-relative paths.
Proposed fix
-→ Read [references/spawning_subagents.md](references/spawning_subagents.md) for how to spawn sub-agents.
+→ Read [spawning_subagents.md](spawning_subagents.md) for how to spawn sub-agents.
-Pass the prompt from [references/cr_agent_prompt.md](references/cr_agent_prompt.md), plus scope description.
+Pass the prompt from [cr_agent_prompt.md](cr_agent_prompt.md), plus scope description.
-- [references/spawning_subagents.md](references/spawning_subagents.md) — How to spawn sub-agents
-- [references/cr_agent_prompt.md](references/cr_agent_prompt.md) — Prompt passed to CR sub-agent
+- [spawning_subagents.md](spawning_subagents.md) — How to spawn sub-agents
+- [cr_agent_prompt.md](cr_agent_prompt.md) — Prompt passed to CR sub-agentAlso applies to: 68-69
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/cmd_code_review.md around lines 20 - 23, The
markdown contains incorrect sibling links like
"references/spawning_subagents.md" and "references/cr_agent_prompt.md" which
resolve to references/references/...; change them to sibling-relative paths
"./spawning_subagents.md" and "./cr_agent_prompt.md" (and update any other
occurrences of those same link strings elsewhere in the file, e.g., the
occurrences near the bottom that mirror lines 68-69) so the links point
correctly to the files in the same directory.
| ``` | ||
| <prior_cr_feedback> | ||
| [Prior CR content here] | ||
| </prior_cr_feedback> | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the fenced example block.
Line 34 starts a fenced block without a language. Tagging it (e.g., xml) keeps markdown lint clean and improves readability.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 34-34: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/cmd_code_review.md around lines 34 - 38, The
fenced example block beginning with the triple backticks that contains the
<prior_cr_feedback> element lacks a language tag; update the opening fence (the
``` that starts the block) to include a language identifier such as xml (e.g.,
change ``` to ```xml) so the block is properly syntax-tagged and markdown lint
warnings are resolved.
| ``` | ||
| project_overview.md → functional_spec.md → ui_design.md (if exists) | ||
| → architecture.md → components/ (if exists) → implementation_plan.md | ||
| ``` |
There was a problem hiding this comment.
Specify a language for the dependency-order fenced block.
Add text to the fence starting at Line 34 to satisfy markdownlint and keep formatting consistent.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 34-34: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/cmd_continue.md around lines 34 - 37, The
fenced code block that currently contains the dependency order list (the block
showing "project_overview.md → functional_spec.md → ui_design.md (if exists) →
architecture.md → components/ (if exists) → implementation_plan.md") should have
a language specified to satisfy markdownlint; change the opening fence from ```
to ```text so the block is marked as plain text and formatting/linting pass for
the fence starting at that dependency-order block.
|
|
||
| 1. **Read the implementation plan** and identify the target phase | ||
| 2. **Read spec and architecture docs** for context | ||
| 3. **Write phase plan** to `/phase_plans/phase_N.md`: |
There was a problem hiding this comment.
Write phase plans to the project-specific path, not repo root.
Line 54 currently points to /phase_plans/phase_N.md, which conflicts with the documented project structure and can place files in the wrong location.
Proposed fix
-3. **Write phase plan** to `/phase_plans/phase_N.md`:
+3. **Write phase plan** to `specs/projects/PROJECT_NAME/phase_plans/phase_N.md`:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 3. **Write phase plan** to `/phase_plans/phase_N.md`: | |
| 3. **Write phase plan** to `specs/projects/PROJECT_NAME/phase_plans/phase_N.md`: |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/cmd_implement.md at line 54, The docs line
currently references the repo-root location `/phase_plans/phase_N.md`; change
that wording in cmd_implement.md so it instructs writers to place phase plans in
the project-specific phase_plans directory (i.e., the phase_plans folder under
the target project), not the repository root—replace the literal
`/phase_plans/phase_N.md` with a project-scoped placeholder that makes the
intended project-local path clear.
| - → Read [references/spawning_subagents.md](references/spawning_subagents.md) for how to spawn | ||
| - Pass the prompt from [references/cr_agent_prompt.md](references/cr_agent_prompt.md) to the sub-agent | ||
| - Include: "A coding agent just implemented phase N of [project]. Review the changes using `git diff`." |
There was a problem hiding this comment.
Fix sibling reference links in this references file.
These links include references/... even though this file already resides in references/, so they likely resolve incorrectly.
Proposed fix
- - → Read [references/spawning_subagents.md](references/spawning_subagents.md) for how to spawn
- - Pass the prompt from [references/cr_agent_prompt.md](references/cr_agent_prompt.md) to the sub-agent
+ - → Read [spawning_subagents.md](spawning_subagents.md) for how to spawn
+ - Pass the prompt from [cr_agent_prompt.md](cr_agent_prompt.md) to the sub-agent
- - → Read [references/spawning_subagents.md](references/spawning_subagents.md) for how to spawn
+ - → Read [spawning_subagents.md](spawning_subagents.md) for how to spawn
-For implement-all, pass the content of [references/coding_phase_prompt.md](references/coding_phase_prompt.md) to each phase sub-agent.
+For implement-all, pass the content of [coding_phase_prompt.md](coding_phase_prompt.md) to each phase sub-agent.
-- [references/spawning_subagents.md](references/spawning_subagents.md) — How to spawn sub-agents
-- [references/coding_phase_prompt.md](references/coding_phase_prompt.md) — Prompt passed to coding sub-agents
-- [references/cr_agent_prompt.md](references/cr_agent_prompt.md) — Prompt passed to CR sub-agents
+- [spawning_subagents.md](spawning_subagents.md) — How to spawn sub-agents
+- [coding_phase_prompt.md](coding_phase_prompt.md) — Prompt passed to coding sub-agents
+- [cr_agent_prompt.md](cr_agent_prompt.md) — Prompt passed to CR sub-agentsAlso applies to: 101-102, 116-122
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/cmd_implement.md around lines 65 - 67, The
sibling links in cmd_implement.md incorrectly include the leading "references/"
prefix (e.g., "references/spawning_subagents.md" and
"references/cr_agent_prompt.md") even though the file already lives in the
references/ directory; update those link targets to be relative within the same
folder (remove the "references/" prefix) for all occurrences (including the ones
at lines ~101-102 and ~116-122) so links point to spawning_subagents.md,
cr_agent_prompt.md, etc.
|
|
||
| ## Pushback | ||
|
|
||
| → Load [references/pushback.md](references/pushback.md) if not already loaded. |
There was a problem hiding this comment.
Incorrect relative path for pushback doc link.
At Line 91, the link should point to pushback.md (or ./pushback.md) from the current directory.
✏️ Suggested edit
-→ Load [references/pushback.md](references/pushback.md) if not already loaded.
+→ Load [pushback.md](pushback.md) if not already loaded.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| → Load [references/pushback.md](references/pushback.md) if not already loaded. | |
| → Load [pushback.md](pushback.md) if not already loaded. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/step_architecture.md at line 91, The
markdown link currently points to "references/pushback.md" which is incorrect
for this directory; update the link target on the arrowed line (the line
containing "→ Load [references/pushback.md](references/pushback.md) if not
already loaded.") to use a relative path to the local file (e.g., "pushback.md"
or "./pushback.md") so the link correctly resolves from this document's
directory.
|
|
||
| ## Pushback | ||
|
|
||
| → Load [references/pushback.md](references/pushback.md) if not already loaded. |
There was a problem hiding this comment.
Fix relative link path to pushback guide.
At Line 81, references/pushback.md likely resolves to a non-existent nested path from this directory. Use pushback.md (or ./pushback.md).
✏️ Suggested edit
-→ Load [references/pushback.md](references/pushback.md) if not already loaded.
+→ Load [pushback.md](pushback.md) if not already loaded.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| → Load [references/pushback.md](references/pushback.md) if not already loaded. | |
| → Load [pushback.md](pushback.md) if not already loaded. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/step_functional_spec.md at line 81, The
Markdown link uses a nested path "references/pushback.md" that likely doesn't
exist relative to step_functional_spec.md; update the link to the correct
relative path "pushback.md" (or "./pushback.md") so the reference resolves
correctly, i.e., replace references/pushback.md with pushback.md in the
document.
|
|
||
| ## Pushback | ||
|
|
||
| → Load [references/pushback.md](references/pushback.md) if not already loaded. |
There was a problem hiding this comment.
Broken relative link to pushback reference.
At Line 57, update the link target to pushback.md (or ./pushback.md) to avoid pointing at references/references/....
✏️ Suggested edit
-→ Load [references/pushback.md](references/pushback.md) if not already loaded.
+→ Load [pushback.md](pushback.md) if not already loaded.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| → Load [references/pushback.md](references/pushback.md) if not already loaded. | |
| → Load [pushback.md](pushback.md) if not already loaded. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/step_ui_design.md at line 57, Update the
broken relative markdown link on the line containing "→ Load
[references/pushback.md](references/pushback.md) if not already loaded." to
point directly to pushback.md (e.g., change the link target to pushback.md or
./pushback.md) so it no longer resolves to references/references/...; ensure the
visible text can remain "references/pushback.md" if desired but the URL target
must be corrected.
| ``` | ||
| Current Project: /specs/projects/project_name | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the state-file example block.
The fenced block is unlabeled; use text for markdownlint compatibility and consistency.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/SKILL.md around lines 107 - 109, The fenced code block
showing "Current Project: /specs/projects/project_name" is unlabeled; update
that triple-backtick fence to specify the language tag `text` so the block
becomes ```text — locate the code block containing the string "Current Project:
/specs/projects/project_name" in SKILL.md and add the `text` tag to the opening
fence for markdownlint compatibility and consistency.
|
|
||
| | Path | Description | | ||
| |------|-------------| | ||
| | `libs/core/` | Python library with the core functionality of Kiln (evals, synthetic data gen, fine tuning, RAG, etc.) | |
There was a problem hiding this comment.
Use hyphenated compound modifier for readability.
At Line 9, change fine tuning to fine-tuning for consistent technical writing style.
✏️ Suggested edit
-| `libs/core/` | Python library with the core functionality of Kiln (evals, synthetic data gen, fine tuning, RAG, etc.) |
+| `libs/core/` | Python library with the core functionality of Kiln (evals, synthetic data gen, fine-tuning, RAG, etc.) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `libs/core/` | Python library with the core functionality of Kiln (evals, synthetic data gen, fine tuning, RAG, etc.) | | |
| | `libs/core/` | Python library with the core functionality of Kiln (evals, synthetic data gen, fine-tuning, RAG, etc.) | |
🧰 Tools
🪛 LanguageTool
[grammar] ~9-~9: Use a hyphen to join words.
Context: ...of Kiln (evals, synthetic data gen, fine tuning, RAG, etc.) | | libs/server/ | ...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@specs/monorepo.md` at line 9, The phrase "fine tuning" in the libs/core
description should use a hyphenated compound modifier; update the string in the
monorepo spec (the table row containing "`libs/core/` | Python library with the
core functionality of Kiln (evals, synthetic data gen, fine tuning, RAG, etc.)")
to read "fine-tuning" so the description becomes "evals, synthetic data gen,
fine-tuning, RAG, etc." to maintain consistent technical writing.
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.cursor/skills/specs/references/cmd_implement.md:
- Line 68: Replace the vague placeholder and non-descriptive link text in the
string that currently reads "A coding agent just implemented phase N of
[project]. Review the changes using `git diff`. The spec for this project can be
found [here](link_to_spec_folder)." — update the markdown to point to a concrete
path pattern (e.g., a relative spec folder pattern like
`specs/<project>/phase-N` or a repo-specific glob) in place of
`link_to_spec_folder`, and change the link text from "[here]" to a descriptive
phrase such as "project spec" or "phase N spec" so the new text clearly
identifies and links to the spec (locate and edit this literal line in the file
content).
In `@agents/code_review_guidelines.md`:
- Line 26: Update the sentence "All visible classes/vars should have docstrings
explaining their purpose. These will be pulled into 3rd party docs
automatically. The doc strings should be written for 3rd party devs learning the
SDK." by hyphenating the compound adjective "3rd party" in both occurrences to
"3rd-party" so it reads "...pulled into 3rd-party docs..." and "...written for
3rd-party devs..."; ensure both instances in the line are changed and keep the
rest of the wording unchanged.
- Around line 15-18: Update the "Python specific guide" heading and wording to
correct grammar: change the heading text "Python specific" to "Python-specific"
and replace the phrase "where ever" with the single word "wherever" in the line
that reads "We use `asyncio` where ever possible. Avoid threads..." so it
becomes "We use `asyncio` wherever possible. Avoid threads..." to ensure correct
hyphenation and word usage.
- Around line 9-10: Update the two typos in the comments guidance: in the
"Unnecessary comments" bullet replace "self explanitory" with "self-explanatory"
and in the "Missing comments" bullet replace "non obvious" with "non-obvious";
locate the phrases within the "Unnecessary comments" and "Missing comments"
lines and apply the corrected hyphenation and spelling.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 05b66928-c219-4888-a321-05dbf3f9b36b
📒 Files selected for processing (3)
.cursor/skills/specs/references/cmd_implement.mdAGENTS.mdagents/code_review_guidelines.md
✅ Files skipped from review due to trivial changes (1)
- AGENTS.md
| 9. **Self code-review via sub-agent**: | ||
| - → Read [references/spawning_subagents.md](references/spawning_subagents.md) for how to spawn | ||
| - Pass the prompt from [references/cr_agent_prompt.md](references/cr_agent_prompt.md) to the sub-agent | ||
| - Include: "A coding agent just implemented phase N of [project]. Review the changes using `git diff`. The spec for this project can be found [here](link_to_spec_folder)." |
There was a problem hiding this comment.
Replace placeholder with specific path pattern and improve link text.
Line 68 contains a vague placeholder link_to_spec_folder that isn't actionable, and the link text "[here]" is non-descriptive.
📝 Proposed fix
- - Include: "A coding agent just implemented phase N of [project]. Review the changes using `git diff`. The spec for this project can be found [here](link_to_spec_folder)."
+ - Include: "A coding agent just implemented phase N of [project]. Review the changes using `git diff`. The spec for this project can be found at `specs/projects/PROJECT_NAME/`."📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Include: "A coding agent just implemented phase N of [project]. Review the changes using `git diff`. The spec for this project can be found [here](link_to_spec_folder)." | |
| - Include: "A coding agent just implemented phase N of [project]. Review the changes using `git diff`. The spec for this project can be found at `specs/projects/PROJECT_NAME/`." |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 68-68: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/specs/references/cmd_implement.md at line 68, Replace the
vague placeholder and non-descriptive link text in the string that currently
reads "A coding agent just implemented phase N of [project]. Review the changes
using `git diff`. The spec for this project can be found
[here](link_to_spec_folder)." — update the markdown to point to a concrete path
pattern (e.g., a relative spec folder pattern like `specs/<project>/phase-N` or
a repo-specific glob) in place of `link_to_spec_folder`, and change the link
text from "[here]" to a descriptive phrase such as "project spec" or "phase N
spec" so the new text clearly identifies and links to the spec (locate and edit
this literal line in the file content).
| - Unnecessary comments: explaining code that is self explanitory, or code that should be explained by function/var names and is instead explained by comments | ||
| - Missing comments: comments should document the "why" not the what. If code does something unexpected, and the "why" is non obvious, the why should be documented. |
There was a problem hiding this comment.
Fix typo and hyphenation in comments guidance.
Two minor issues in the code comments section:
- Line 9: "self explanitory" should be "self-explanatory"
- Line 10: "non obvious" should be "non-obvious"
📝 Proposed fix
- - Unnecessary comments: explaining code that is self explanitory, or code that should be explained by function/var names and is instead explained by comments
- - Missing comments: comments should document the "why" not the what. If code does something unexpected, and the "why" is non obvious, the why should be documented.
+ - Unnecessary comments: explaining code that is self-explanatory, or code that should be explained by function/var names and is instead explained by comments
+ - Missing comments: comments should document the "why" not the what. If code does something unexpected, and the "why" is non-obvious, the why should be documented.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Unnecessary comments: explaining code that is self explanitory, or code that should be explained by function/var names and is instead explained by comments | |
| - Missing comments: comments should document the "why" not the what. If code does something unexpected, and the "why" is non obvious, the why should be documented. | |
| - Unnecessary comments: explaining code that is self-explanatory, or code that should be explained by function/var names and is instead explained by comments | |
| - Missing comments: comments should document the "why" not the what. If code does something unexpected, and the "why" is non-obvious, the why should be documented. |
🧰 Tools
🪛 LanguageTool
[grammar] ~10-~10: Use a hyphen to join words.
Context: ...mething unexpected, and the "why" is non obvious, the why should be documented. -...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@agents/code_review_guidelines.md` around lines 9 - 10, Update the two typos
in the comments guidance: in the "Unnecessary comments" bullet replace "self
explanitory" with "self-explanatory" and in the "Missing comments" bullet
replace "non obvious" with "non-obvious"; locate the phrases within the
"Unnecessary comments" and "Missing comments" lines and apply the corrected
hyphenation and spelling.
| ### Python specific guide | ||
|
|
||
| - Code should be "Pythonic" | ||
| - We use `asyncio` where ever possible. Avoid threads unless there's a good reason we can't use async. |
There was a problem hiding this comment.
Fix grammar issues in Python section.
Two grammar corrections needed:
- Line 15: "Python specific" should be "Python-specific"
- Line 18: "where ever" should be "wherever"
📝 Proposed fix
-### Python specific guide
+### Python-specific guide
- Code should be "Pythonic"
-- We use `asyncio` where ever possible. Avoid threads unless there's a good reason we can't use async.
+- We use `asyncio` wherever possible. Avoid threads unless there's a good reason we can't use async.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Python specific guide | |
| - Code should be "Pythonic" | |
| - We use `asyncio` where ever possible. Avoid threads unless there's a good reason we can't use async. | |
| ### Python-specific guide | |
| - Code should be "Pythonic" | |
| - We use `asyncio` wherever possible. Avoid threads unless there's a good reason we can't use async. |
🧰 Tools
🪛 LanguageTool
[grammar] ~15-~15: Use a hyphen to join words.
Context: ...ally called from many apps). ### Python specific guide - Code should be "Python...
(QB_NEW_EN_HYPHEN)
[grammar] ~18-~18: Ensure spelling is correct
Context: ...should be "Pythonic" - We use asyncio where ever possible. Avoid threads unless there's ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@agents/code_review_guidelines.md` around lines 15 - 18, Update the "Python
specific guide" heading and wording to correct grammar: change the heading text
"Python specific" to "Python-specific" and replace the phrase "where ever" with
the single word "wherever" in the line that reads "We use `asyncio` where ever
possible. Avoid threads..." so it becomes "We use `asyncio` wherever possible.
Avoid threads..." to ensure correct hyphenation and word usage.
| The SDK in `/libs/core` is a SDK/library we expose to third parties. We code review it with additional standards. | ||
|
|
||
| - Changing existing APIs that break current users should be avoided. Call out breaking API changes, and confirm with user that we're okay with this break. | ||
| - All visible classes/vars should have docstrings explaining their purpose. These will be pulled into 3rd party docs automatically. The doc strings should be written for 3rd party devs learning the SDK. |
There was a problem hiding this comment.
Add hyphens to "3rd-party" compound adjective.
"3rd party" should be hyphenated when used as a compound adjective (appears twice on this line).
📝 Proposed fix
-- All visible classes/vars should have docstrings explaining their purpose. These will be pulled into 3rd party docs automatically. The doc strings should be written for 3rd party devs learning the SDK.
+- All visible classes/vars should have docstrings explaining their purpose. These will be pulled into 3rd-party docs automatically. The doc strings should be written for 3rd-party devs learning the SDK.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - All visible classes/vars should have docstrings explaining their purpose. These will be pulled into 3rd party docs automatically. The doc strings should be written for 3rd party devs learning the SDK. | |
| - All visible classes/vars should have docstrings explaining their purpose. These will be pulled into 3rd-party docs automatically. The doc strings should be written for 3rd-party devs learning the SDK. |
🧰 Tools
🪛 LanguageTool
[grammar] ~26-~26: Use a hyphen to join words.
Context: ...r purpose. These will be pulled into 3rd party docs automatically. The doc string...
(QB_NEW_EN_HYPHEN)
[grammar] ~26-~26: Use a hyphen to join words.
Context: ...he doc strings should be written for 3rd party devs learning the SDK. - Performan...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@agents/code_review_guidelines.md` at line 26, Update the sentence "All
visible classes/vars should have docstrings explaining their purpose. These will
be pulled into 3rd party docs automatically. The doc strings should be written
for 3rd party devs learning the SDK." by hyphenating the compound adjective "3rd
party" in both occurrences to "3rd-party" so it reads "...pulled into 3rd-party
docs..." and "...written for 3rd-party devs..."; ensure both instances in the
line are changed and keep the rest of the wording unchanged.
2 participants
A new skill for using the "spec-driven-dev" approach
Summary by CodeRabbit
Documentation
Chores