diff --git a/packages/agents/content/skills/_data/next-steps-after-review.md b/packages/agents/content/skills/_data/next-steps-after-review.md new file mode 100644 index 00000000..db2b6a6b --- /dev/null +++ b/packages/agents/content/skills/_data/next-steps-after-review.md @@ -0,0 +1,95 @@ +# Next steps after review + +Standard next-steps block for skills that produce a code review. Skills reference this file to maintain a consistent format and recommendation logic. + +The next-steps block has two independent sub-blocks. Each is shown only when its condition is met. If neither condition is met, no next-steps block appears. Whether one or both sub-blocks are shown, always wrap the output in a `Next steps:` header. + +## Deviations sub-block + +Shown when the ticket compliance section reports gaps (partial or unaddressed acceptance criteria) or unplanned work. + +### Options + +| Option | Description | +| ------------- | ---------------------------------------------------- | +| Update ticket | Revise the ticket to match the actual implementation | +| Leave as-is | Accept the deviation without updating the ticket | + +### Output format + +``` +Next steps: + +Deviations from ticket: + ▶ Update ticket (recommended): Use the `design-and-plan` skill with ticket: {ticket_source} + · Leave as-is +``` + +`Leave as-is` never receives the `▶` marker -- it is the passive alternative, not a recommendation. + +### Recommendation rules + +1. **Recommend "Update ticket"** (`▶`) -- acceptance criteria are missing or substantially different from what was implemented, OR significant unplanned work was done that should be captured +2. **No recommendation** -- deviations are minor and intentional (e.g., a criterion was addressed differently than originally described but the intent is met). Present both options with `·` markers (without `(recommended)`); the user decides. + +When uncertain, recommend updating the ticket. + +## Findings sub-block + +Shown when the review contains actionable findings (F, W, or T categories). + +### Options + +| Option | Description | +| ------------------ | ---------------------------------------------- | +| Design and plan | Rethink the approach before fixing | +| Orchestrate | Run the full orchestrated development pipeline | +| Implement directly | Implement fixes without orchestration | + +### Output format + +``` +Next steps: + +Actionable findings: + ▶ {recommended option} (recommended): Use the `{skill-name}` skill with ticket: {ticket_source} + · {second option}: Use the `{skill-name}` skill with ticket: {ticket_source} + · {third option} +``` + +Mark the recommended option with `▶` and others with `·`. Include all known paths (ticket) in each option line; omit paths that are not available in the current context. + +Skill names for each option: + +- **Design and plan** -> `design-and-plan` +- **Orchestrate** -> `orchestrate-dev` +- **Implement directly** -> no skill invocation; the user implements manually or asks the agent to begin + +### Recommendation rules + +Select the recommended option using these rules in priority order: + +1. **Design and plan** -- findings suggest the approach needs rethinking (e.g., architectural issues, fundamental design problems, multiple FIXMEs that point to a flawed strategy) +2. **Orchestrate** -- findings are non-trivial but the approach is sound (e.g., a mix of warnings and TODOs, or FIXMEs that are localized fixes) +3. **Implement directly** -- findings are simple and well-understood (e.g., a few TODOs, minor warnings with obvious fixes) + +When uncertain between two options, recommend the more thorough one. + +Each skill supplies its own recommendation context (e.g., finding counts and categories, severity of deviations). Apply these rules using that context. + +## Combined output format + +When both sub-blocks are shown, present them as separate sections within a single next-steps block: + +``` +Next steps: + +Deviations from ticket: + ▶ Update ticket (recommended): Use the `design-and-plan` skill with ticket: {ticket_source} + · Leave as-is + +Actionable findings: + ▶ Orchestrate (recommended): Use the `orchestrate-dev` skill with ticket: {ticket_source} + · Design and plan: Use the `design-and-plan` skill with ticket: {ticket_source} + · Implement directly +``` diff --git a/packages/agents/content/skills/review-change/SKILL.md b/packages/agents/content/skills/review-change/SKILL.md index 533b3dc1..a72b7c38 100644 --- a/packages/agents/content/skills/review-change/SKILL.md +++ b/packages/agents/content/skills/review-change/SKILL.md @@ -12,17 +12,39 @@ Act as a conscientious code reviewer for changes in the current scope. - _(no arguments)_: Review branch changes (default scope) - `commit []`: Review a specific commit (HEAD if ref omitted) +- `ticket ` _(optional, branch scope only)_: Ticket or requirements to check code against. Source resolution: + +| Input form | Resolution | +| ----------------------------------------------------------- | --------------------------------------------------------- | +| URL to a known platform (GitHub, Jira, etc.) | Use platform CLI or WebFetch to retrieve issue content | +| Other URL | WebFetch the URL content | +| Shorthand reference (`#99`, `issue 99`, `GitHub issue #99`) | Resolve platform (see below), then fetch via platform CLI | +| File path | Read the file | +| Plain text | Use as-is | + +**Shorthand reference resolution** — determine which platform `#99` refers to: + +1. Check `.agents/preferences.yaml` -> `integrations` (if exactly one enabled, use it; if multiple, ask) +2. Check `git remote get-url origin` (e.g., `github.com` -> GitHub) +3. Ask the user + +For GitHub: `gh issue view --json number,title,body,labels {number}` ## Process 1. **Get context** using `get-session-context` to obtain `default_branch`, `ticket_id`, `project_slug`, and `artifact_base_dir` -2. **Read prior artifacts** — if a run directory exists for this ticket, read all artifacts chronologically for context (including any prior dispositions). _(Branch scope only.)_ -3. **Analyze changes**: +2. **Resolve ticket** _(branch scope only)_ — resolve the ticket source using this priority order: + 1. **Explicit argument** — if a `ticket` argument was provided, resolve it per the [Arguments](#arguments) table + 2. **Auto-resolve** — if no argument, scan `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` for the most recent `*_ticket.md` file and read it + 3. **No ticket found** — skip ticket compliance; review proceeds without it +3. **Read prior artifacts** — if a run directory exists for this ticket, read all artifacts chronologically for context (including any prior dispositions). _(Branch scope only.)_ +4. **Analyze changes**: - Branch scope: `git diff $DEFAULT_BRANCH...HEAD` - Commit scope: `git diff ^..` (or `git show ` for context) -4. **Review thoroughly** following the guidelines below -5. **Assign a score** out of 10 -6. **Save the review** per the [Saving](#saving) section +5. **Review thoroughly** following the guidelines below +6. **Assign a score** out of 10 +7. **Save the review** per the [Saving](#saving) section +8. **Present next steps** _(branch scope only)_ — after saving, present a next-steps prompt following [next-steps-after-review](_data/next-steps-after-review.md). Supply recommendation context: finding counts and categories from the review, and whether ticket compliance gaps or unplanned work were identified. The next-steps prompt is interactive output only and is not saved in the review artifact. ## Review guidelines @@ -107,6 +129,28 @@ Generated by: {Agent name} (model: {model}) ## Conclusion Score: X/10 + +## Ticket compliance + +{Omit this entire section when no ticket is available. Include it when a ticket was resolved, even if all criteria are met and no unplanned work exists.} + +### Acceptance criteria + +| # | Criterion | Status | Notes | +| --- | ---------------- | -------- | ------- | +| 1 | {criterion text} | {status} | {notes} | + +Status values: ✅ Met, ⚠️ Partial, ❌ Not addressed + +Extract criteria from whatever structure the ticket uses (numbered lists, checkboxes, prose). If the ticket does not have clearly delimited acceptance criteria, derive them from the ticket's problem statement and solution description. + +### Unplanned work + +{Bullet list of changes not traceable to any acceptance criterion. If none, state "None."} + +### Assessment + +{1-2 sentence summary of alignment between the implementation and the ticket requirements.} ``` ### Commit scope