codeassembly-guidance 0.0.0 โ 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: refine-plan
|
|
3
|
+
description: Review and refine an implementation plan for completeness and correctness
|
|
4
|
+
user-invocable: true
|
|
5
|
+
dependencies:
|
|
6
|
+
subagents:
|
|
7
|
+
- plan-reviewer
|
|
8
|
+
- plan-reviser
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Refine plan
|
|
12
|
+
|
|
13
|
+
Perform a single review-and-revise round on a saved implementation plan, checking for completeness (decision gaps that the coder would fill) and correctness (factual accuracy against the codebase). Produces a refined plan ready for implementation.
|
|
14
|
+
|
|
15
|
+
## Arguments
|
|
16
|
+
|
|
17
|
+
- Plan file path (required): Path to a saved plan artifact (e.g., the `{timestamp}_{slug}_plan.md` from `save-plan`)
|
|
18
|
+
- Ticket source (required): File path or URL (GitHub issue URL, Jira URL, etc.)
|
|
19
|
+
|
|
20
|
+
## Visibility
|
|
21
|
+
|
|
22
|
+
Before every {tool:Task} call and after every phase completion, output a status line:
|
|
23
|
+
|
|
24
|
+
- **Before dispatch:** `-- Refine plan -- delegating to {agent}...`
|
|
25
|
+
- **After completion:** `-- Refine plan -- {summary}`
|
|
26
|
+
|
|
27
|
+
## Flow
|
|
28
|
+
|
|
29
|
+
### 1. Validate inputs and resolve context
|
|
30
|
+
|
|
31
|
+
1. Read the plan file. If not found, report an error and stop.
|
|
32
|
+
2. Parse YAML frontmatter from the plan content. If a `provenance` block is present, store it as `{input-provenance}`. If the plan does not have frontmatter or a `provenance` block, set `{input-provenance}` to empty.
|
|
33
|
+
3. Resolve the ticket source:
|
|
34
|
+
- GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body {url}` via Bash to fetch content.
|
|
35
|
+
- File path -> Read the file.
|
|
36
|
+
- Other URL -> Fetch the URL content.
|
|
37
|
+
4. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout.
|
|
38
|
+
5. Resolve artifact directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
39
|
+
6. `mkdir -p {artifact_dir}`
|
|
40
|
+
|
|
41
|
+
### 2. Dispatch plan-reviewer
|
|
42
|
+
|
|
43
|
+
Extract the slug from the original plan filename. The slug is the middle segment of `{timestamp}_{slug}_{artifact-type}.md`. If the filename doesn't follow this pattern, derive a slug from the filename.
|
|
44
|
+
|
|
45
|
+
Generate a UTC timestamp: `{YYYYMMDD-HHMMSSZ}`.
|
|
46
|
+
|
|
47
|
+
Set the review output path: `{artifact_dir}/{timestamp}_{slug}_plan-review.md`
|
|
48
|
+
|
|
49
|
+
`-- Refine plan -- delegating to plan-reviewer...`
|
|
50
|
+
|
|
51
|
+
Call {tool:Task} with `subagent_type: plan-reviewer`, `max_turns: 30`:
|
|
52
|
+
|
|
53
|
+
> Review the following implementation plan for completeness and correctness.
|
|
54
|
+
>
|
|
55
|
+
> **Plan file:** {plan_path}
|
|
56
|
+
>
|
|
57
|
+
> **Ticket/requirements:**
|
|
58
|
+
> {ticket content}
|
|
59
|
+
>
|
|
60
|
+
> **Output path:** {review_output_path}
|
|
61
|
+
|
|
62
|
+
Parse the return block:
|
|
63
|
+
|
|
64
|
+
- `Status`: Must be `completed`
|
|
65
|
+
- `AutoResolvable`: Integer count of auto-resolvable findings
|
|
66
|
+
- `UserQuestions`: Integer count of findings requiring user input
|
|
67
|
+
|
|
68
|
+
`-- Refine plan -- {AutoResolvable + UserQuestions} findings ({AutoResolvable} auto-resolvable, {UserQuestions} require user input)`
|
|
69
|
+
|
|
70
|
+
### 3. Present user questions
|
|
71
|
+
|
|
72
|
+
Evaluate the finding counts:
|
|
73
|
+
|
|
74
|
+
- **0 total findings** (AutoResolvable = 0 AND UserQuestions = 0): Skip the reviser entirely. Report that the plan does not need any refinement, then present next steps.
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
Plan reviewed -- no findings. The plan is ready for implementation.
|
|
78
|
+
Review: {review_output_path}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
<HARD-GATE>
|
|
82
|
+
Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The plan was just reviewed, and the review did not find any issues; use this as recommendation context. Use `{plan_path}` (the original plan argument, not `{revision_output_path}`; this path does not produce a revised plan) and `{ticket_source}` in each skill-invoking option line.
|
|
83
|
+
</HARD-GATE>
|
|
84
|
+
|
|
85
|
+
- **0 user questions** (UserQuestions = 0, AutoResolvable > 0): Skip user interaction. Proceed to step 4 with empty user answers.
|
|
86
|
+
|
|
87
|
+
- **User questions present** (UserQuestions > 0): Read the review artifact. Extract all findings from the "Decision gaps" section (these may be C or X findings -- the section is organized by resolution type, not finding category). Present each finding's question using the finding's ID (e.g., `C1`, `X2`) as the question identifier. When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
The plan review identified {UserQuestions} question(s) that need your input:
|
|
91
|
+
|
|
92
|
+
**C1: {title}**
|
|
93
|
+
{question text}
|
|
94
|
+
1. โ โ โ {recommended option}:
|
|
95
|
+
- โ {strongest argument}
|
|
96
|
+
- โ {secondary argument}
|
|
97
|
+
2. โ โกโก {alternative option}:
|
|
98
|
+
- โ {pro}
|
|
99
|
+
- โ {con}
|
|
100
|
+
|
|
101
|
+
**X2: {title}**
|
|
102
|
+
{open-ended question text: describe what you want in free-form text}
|
|
103
|
+
|
|
104
|
+
Please answer using the finding ID (e.g., "C1: Option 2; X2: ..."), or respond in free-form text.
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Wait for the user's response. Capture their answers as `user_answers`.
|
|
108
|
+
|
|
109
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
110
|
+
|
|
111
|
+
### 4. Dispatch plan-reviser
|
|
112
|
+
|
|
113
|
+
Generate a new UTC timestamp for the refined plan.
|
|
114
|
+
|
|
115
|
+
Set the revision output path: `{artifact_dir}/{new_timestamp}_{slug}_plan-v2.md`
|
|
116
|
+
|
|
117
|
+
`-- Refine plan -- delegating to plan-reviser...`
|
|
118
|
+
|
|
119
|
+
Call {tool:Task} with `subagent_type: plan-reviser`, `max_turns: 30`:
|
|
120
|
+
|
|
121
|
+
> Revise the following implementation plan based on review findings and user answers.
|
|
122
|
+
>
|
|
123
|
+
> **Original plan:** {plan_path}
|
|
124
|
+
> **Review findings:** {review_output_path}
|
|
125
|
+
> **User answers:** {user_answers or "No user answers -- all findings are auto-resolvable."}
|
|
126
|
+
>
|
|
127
|
+
> **Ticket/requirements:**
|
|
128
|
+
> {ticket content}
|
|
129
|
+
>
|
|
130
|
+
> **Output path:** {revision_output_path}
|
|
131
|
+
|
|
132
|
+
Parse the return block:
|
|
133
|
+
|
|
134
|
+
- `Status`: Must be `completed`
|
|
135
|
+
- `Artifact`: Path to the refined plan
|
|
136
|
+
|
|
137
|
+
`-- Refine plan -- revision complete`
|
|
138
|
+
|
|
139
|
+
If the plan-reviser {tool:Task} failed or the return block does not have `Status: completed`, skip the provenance update and report the failure:
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
Plan revision failed -- the plan-reviser did not complete successfully.
|
|
143
|
+
Review: {review_output_path}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Stop here. Do not attempt provenance update or report completion.
|
|
147
|
+
|
|
148
|
+
Stamp the revised plan with frontmatter conforming to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema plus the [plan provenance](../_data/artifact-conventions.md#plan-provenance) extensions. This is the single write point for the revised plan's frontmatter: `plan-reviser` does not output any frontmatter of its own; `refine-plan` owns it.
|
|
149
|
+
|
|
150
|
+
The stamp writes the full canonical schema in one atomic write: the `provenance:` block plus the top-level canonical fields.
|
|
151
|
+
|
|
152
|
+
The top-level fields come from the script; the `provenance:` block is computed from `{input-provenance}` plus the stamping logic below.
|
|
153
|
+
|
|
154
|
+
This site uses `--format json` because the `provenance:` block is case-branched on the input artifact's existing provenance; see [artifact-conventions.md](../_data/artifact-conventions.md#bespoke-frontmatter-composition).
|
|
155
|
+
|
|
156
|
+
Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --format json` via Bash. It emits a JSON object with the universal artifact fields (`branch`, `commit`, `baseSha`, `pr`, `ticket_id`, `ticket_ref`, `scm`, `timestamp`, `run_id`). Use those values verbatim for the matching YAML keys. Optional fields that the script omits from its output (`baseSha`, `pr`, `ticket_id`, `ticket_ref`, `run_id`) must be omitted from the frontmatter too; do not emit `null` or empty strings.
|
|
157
|
+
|
|
158
|
+
The `provenance:` block is **not** populated from the script. Construct it manually per the case branches below.
|
|
159
|
+
|
|
160
|
+
**Round-trip preservation:** The top-level canonical fields (`branch`, `commit`, etc.) are always re-resolved from current session context via the script; they are not carried forward from `{input-provenance}`. This is correct: The output is a new artifact at a new point in time on a potentially different branch. The `provenance:` block's camelCase convention (`baseSha`, `isInteractive`, `refinedBy`) is preserved as-is on both read and write; the keys are not renamed. Provenance fields carried forward from the input are `skill`, `baseSha`, `isInteractive`, and `iteration` (per the case branches).
|
|
161
|
+
|
|
162
|
+
**When `{input-provenance}` is non-empty:**
|
|
163
|
+
|
|
164
|
+
1. Use the script's `baseSha` as the new value. If the script omitted `baseSha`, preserve the original `baseSha` from `{input-provenance}`.
|
|
165
|
+
2. Read the revised plan file at `{revision_output_path}`.
|
|
166
|
+
3. Construct updated provenance:
|
|
167
|
+
- `skill`: Preserve from `{input-provenance}` (the original authoring skill)
|
|
168
|
+
- `refinedBy`: Set to `refine-plan`
|
|
169
|
+
- `timestamp`: Use the script's `timestamp`
|
|
170
|
+
- `baseSha`: The script's value (or preserved original)
|
|
171
|
+
- `isInteractive`: Preserve from `{input-provenance}` if present
|
|
172
|
+
- `iteration`: If `{input-provenance}.iteration` is present, set to `{input-provenance}.iteration + 1`. If absent, set to `2`.
|
|
173
|
+
4. Prepend the unified YAML frontmatter (`provenance:` block plus top-level canonical fields from the script) to the revised plan and write back. Example output (assuming input had `skill: design-and-plan` and `isInteractive: true` but did not have an `iteration` field):
|
|
174
|
+
|
|
175
|
+
```markdown
|
|
176
|
+
---
|
|
177
|
+
provenance:
|
|
178
|
+
skill: design-and-plan
|
|
179
|
+
refinedBy: refine-plan
|
|
180
|
+
timestamp: 2026-03-10T08:00:00Z
|
|
181
|
+
baseSha: abc123def456...
|
|
182
|
+
isInteractive: true
|
|
183
|
+
iteration: 2
|
|
184
|
+
ticket_id: '537'
|
|
185
|
+
ticket_ref: '#537'
|
|
186
|
+
branch: 537/feat/example
|
|
187
|
+
commit: 1d2c3b4
|
|
188
|
+
---
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
Include `isInteractive` only if it was present in `{input-provenance}`. Include `baseSha` only if available. Top-level fields follow the script's omit rules.
|
|
192
|
+
|
|
193
|
+
**When `{input-provenance}` is empty:**
|
|
194
|
+
|
|
195
|
+
1. Use the script's `baseSha`. If the script omitted it, omit it.
|
|
196
|
+
2. Read the revised plan file at `{revision_output_path}`.
|
|
197
|
+
3. Construct provenance:
|
|
198
|
+
- `skill`: `unknown`
|
|
199
|
+
- `refinedBy`: `refine-plan`
|
|
200
|
+
- `timestamp`: Script's value
|
|
201
|
+
- `baseSha`: Script's value (omit when absent)
|
|
202
|
+
- `isInteractive`: Always `true`. `refine-plan` is an interactive user-invocable skill: When it stamps a plan without prior provenance, the stamp itself is always produced inside that interactive session.
|
|
203
|
+
- `iteration`: `2`
|
|
204
|
+
4. Prepend the unified YAML frontmatter and write back:
|
|
205
|
+
|
|
206
|
+
```markdown
|
|
207
|
+
---
|
|
208
|
+
provenance:
|
|
209
|
+
skill: unknown
|
|
210
|
+
refinedBy: refine-plan
|
|
211
|
+
timestamp: 2026-03-10T08:00:00Z
|
|
212
|
+
baseSha: abc123def456...
|
|
213
|
+
isInteractive: true
|
|
214
|
+
iteration: 2
|
|
215
|
+
ticket_id: '537'
|
|
216
|
+
ticket_ref: '#537'
|
|
217
|
+
branch: 537/feat/example
|
|
218
|
+
commit: 1d2c3b4
|
|
219
|
+
---
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### 5. Offer ticket update if approach diverged
|
|
223
|
+
|
|
224
|
+
Compare the revised plan's approach/solution with the source ticket's solution section. If they materially diverge, offer to update the ticket to match the revised plan. If the approaches haven't diverged, skip this step silently.
|
|
225
|
+
|
|
226
|
+
**Material divergence** means a different technical approach (e.g., build-time flag changed to runtime detection) or changed scope boundaries (features added or removed). **Non-divergence** means refined details within the same approach (e.g., different function names, reordered steps).
|
|
227
|
+
|
|
228
|
+
On consent, write the update per [platform-specific write](../_data/ticket-source-resolution.md#platform-specific-write), which resolves the platform and states how a revision confined to the solution section composes.
|
|
229
|
+
|
|
230
|
+
This is a shared-state action; do not update without explicit consent. If the user declines, continue to step 6.
|
|
231
|
+
|
|
232
|
+
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
233
|
+
|
|
234
|
+
### 6. Report completion and present next steps
|
|
235
|
+
|
|
236
|
+
```
|
|
237
|
+
Plan refined:
|
|
238
|
+
Review: {review_output_path}
|
|
239
|
+
Revised: {revision_output_path}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
<HARD-GATE>
|
|
243
|
+
Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The plan was just reviewed. If the review identified significant scope changes or unresolved questions that led to a dramatic revision, the plan may warrant another refinement round; otherwise apply the recommendation rules, with a revision that grew the plan as evidence for rule 2. Use this as recommendation context. Include both `{revision_output_path}` (as the plan path) and `{ticket_source}` in each skill-invoking option line.
|
|
244
|
+
</HARD-GATE>
|
|
245
|
+
|
|
246
|
+
## Edge cases
|
|
247
|
+
|
|
248
|
+
- **Ticket URL unreachable**: Report error with the URL and suggest verifying access (e.g., `gh auth status` for GitHub URLs).
|
|
249
|
+
|
|
250
|
+
## Constraints
|
|
251
|
+
|
|
252
|
+
- All codebase exploration is delegated to the subagents -- do not analyze code directly.
|
|
253
|
+
- The user interaction step is conversational -- present questions as formatted text and wait for a free-form response.
|
|
254
|
+
- This skill performs one review-and-revise round. Do not loop or iterate.
|
|
255
|
+
- The original plan file is never modified. All output goes to new artifact files.
|
|
256
|
+
|
|
257
|
+
<!-- include: ../_partials/next-steps-after-plan.md / -->
|
|
258
|
+
|
|
259
|
+
<!-- include: ../_partials/option-format.md / -->
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: respond-to-review
|
|
3
|
+
description: Produce structured response to code review findings with dispositions for each finding
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Respond to review
|
|
8
|
+
|
|
9
|
+
Evaluate code review findings with technical rigor and produce a change summary with embedded dispositions.
|
|
10
|
+
|
|
11
|
+
## Purpose
|
|
12
|
+
|
|
13
|
+
This skill runs between receiving a code review and implementing fixes. The agent evaluates each finding against the actual codebase, decides what to accept or push back on, and documents that reasoning (all embedded in a `coder_change-summary` artifact alongside any code changes made).
|
|
14
|
+
|
|
15
|
+
## Arguments
|
|
16
|
+
|
|
17
|
+
- No arguments: Locate the most recent `reviewer_review` in the active run for the current ticket
|
|
18
|
+
- `<path>`: Respond to the review at the specified path
|
|
19
|
+
|
|
20
|
+
## Process
|
|
21
|
+
|
|
22
|
+
1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `ticket_id`, `ticket_ref`, `project_slug`, `artifact_base_dir`, and `pr_url` from it.
|
|
23
|
+
2. **Locate the review** per the [Locating the review](#locating-the-review) section
|
|
24
|
+
3. **Read prior artifacts** in the review's run directory chronologically for full context
|
|
25
|
+
4. **Parse findings**: Extract all numbered findings (F{n}, W{n}, T{n}, R{n}, S{n}, and legacy variants with `-L` suffix). See [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix) for category definitions.
|
|
26
|
+
5. **Evaluate each finding** following the evaluation protocol below.
|
|
27
|
+
6. **Audit the diff** per [Diff audit](#diff-audit). Every fix that you implemented is verified here, before any of it is written down.
|
|
28
|
+
7. **Commit the fixes** per `{skill:create-commit}`, so that the response narrates work already recorded. A response that does not implement any fix commits nothing; skip this step there rather than composing an empty commit. Rejecting every finding is one such response, as are a review without findings, a legacy observation merely acknowledged, and an ACCEPT whose change is merged in a follow-up.
|
|
29
|
+
8. **Write response** per the output format
|
|
30
|
+
9. **Resolve frontmatter fields** per [Frontmatter resolution](#frontmatter-resolution)
|
|
31
|
+
10. **Save** per the [Saving](#saving) section
|
|
32
|
+
|
|
33
|
+
## Frontmatter resolution
|
|
34
|
+
|
|
35
|
+
The artifact's frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
|
|
36
|
+
|
|
37
|
+
Source `{model_id}` from your system-prompt environment block: the line `model named ... model ID is ...`. Resolve `{review_filename}` to the bare filename of the review being responded to (e.g., `09_reviewer_review.md`).
|
|
38
|
+
|
|
39
|
+
Resolve `{pr_url}` per the [`respond-to-review` path](../_data/pr-source-resolution.md#respond-to-review-path) in PR source resolution:
|
|
40
|
+
|
|
41
|
+
- If the review's frontmatter has a `pr:` field, take `{pr_url}` from it so that the response inherits the same PR backlink, and persist it for future sessions: `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --set-pr-url "{pr_url}"`.
|
|
42
|
+
- Otherwise, fall back to the stored manifest `pr_url` read from the session-context JSON emitted in step 1; if that is also null, `{pr_url}` does not have a value.
|
|
43
|
+
|
|
44
|
+
Run via Bash, writing each resolved value into the call as literal text and dropping the `--override` flag if `{pr_url}` does not have a value:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
{harness_home_dir}/scripts/resolve-frontmatter.sh \
|
|
48
|
+
--skill respond-to-review \
|
|
49
|
+
--interactive true \
|
|
50
|
+
--model "{model_id}" \
|
|
51
|
+
--extra "responding_to={review_filename}" \
|
|
52
|
+
--override "pr={pr_url}"
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Prepend the script's output verbatim to the artifact body.
|
|
56
|
+
|
|
57
|
+
## Locating the review
|
|
58
|
+
|
|
59
|
+
### Explicit path
|
|
60
|
+
|
|
61
|
+
If a path argument is provided, read the review directly from that path. If the file does not exist or does not contain any parseable findings, stop and report the error.
|
|
62
|
+
|
|
63
|
+
### Auto-discovery (default)
|
|
64
|
+
|
|
65
|
+
If the invocation does not include a path, find the most recent `reviewer_review` in the active run:
|
|
66
|
+
|
|
67
|
+
1. Resolve the ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
68
|
+
2. Invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs latest --ticket-dir <ticket-dir>` via Bash. The helper prints `{ "reviewPath": "<path>", "runDir": "<path>" }`: the ticket's active run, per [artifact conventions](../_data/artifact-conventions.md#run-directories), and the newest reviewer or overseer review in it.
|
|
69
|
+
|
|
70
|
+
If the helper exits non-zero, the ticket directory does not contain an active run or the active run does not contain a review; stop and report the message that it printed on stderr.
|
|
71
|
+
|
|
72
|
+
<!-- guidance-hook: ticketing-preferences -->
|
|
73
|
+
|
|
74
|
+
## Evaluation protocol
|
|
75
|
+
|
|
76
|
+
For each finding, apply technical rigor:
|
|
77
|
+
|
|
78
|
+
<HARD-GATE>
|
|
79
|
+
**Anti-sycophancy rules for review response:**
|
|
80
|
+
|
|
81
|
+
1. **Verify before accepting.** Read the actual code referenced in each finding. Do not accept a finding at face value. "The reviewer may have a point" is not rigorous: Either the finding is valid or it isn't.
|
|
82
|
+
2. **Check correctness.** Is the reviewer's claim technically accurate for this specific codebase and context?
|
|
83
|
+
3. **Treat hedging language as a signal.** When a recommendation relies on "plausibly", "arguably", "could", or "no current evidence against", treat the premise as an unverified hypothesis. Require independent verification before acceptance. If the premise cannot be verified, default to REJECT.
|
|
84
|
+
4. **Consider intent.** Is the current implementation a deliberate design choice? Check commit messages, comments, and surrounding patterns.
|
|
85
|
+
5. **Pushback is the default for structural recommendations.** When a recommendation is to move, promote, or restructure code or guidance across files, modules, or sections, read the destination's stated scope, conventions, and invariants in full and verify the item fits, not just that it could syntactically live there. Acceptance requires affirmative evidence; rejection does not. Reject moves that conflict with the destination's stated category, conventions, or framing, even when the destination would "read cleaner." Accept when the destination's stated doctrine clearly accommodates the item and the move resolves a duplication or location problem that the original placement created.
|
|
86
|
+
6. **Partial acceptance is fine.** A finding may be partly correct. Accept the valid parts, reject the invalid parts, and explain the boundary.
|
|
87
|
+
7. **Disposition is decided on substance, not on the reviewer's suggested handling.** Phrases like "consider a follow-up," "no action this PR," "future-coverage work" are the reviewer's priority signal, not a license to defer. The disposition (ACCEPT / REJECT / PARTIAL) is the agent's decision based on whether the change belongs in the codebase. `ACCEPT (follow-up)` is not a valid disposition: If a change belongs but doesn't fit this PR, the disposition is ACCEPT and the follow-up is a separate decision; if the change does not belong, the disposition is REJECT.
|
|
88
|
+
</HARD-GATE>
|
|
89
|
+
|
|
90
|
+
Implementing an ACCEPTed finding means editing code. Apply [Comment discipline](#comment-discipline) as you write. The reviewer conversation must not appear in the source.
|
|
91
|
+
|
|
92
|
+
## Worked examples
|
|
93
|
+
|
|
94
|
+
### Bad โ Good: Hedged move with doctrinal conflict
|
|
95
|
+
|
|
96
|
+
**Review recommendation:** "Move `validateSessionToken` from `auth/validators.ts` into `shared/utils.ts`. It plausibly belongs in a general utility module; there's no current evidence the function needs auth-specific context."
|
|
97
|
+
|
|
98
|
+
**Bad: Uncritical acceptance:**
|
|
99
|
+
|
|
100
|
+
> R1: ACCEPT. `validateSessionToken` is a small input-to-boolean function with no side effects; it composes naturally with the other helpers in `shared/utils.ts`. Moving it consolidates similar shape-based utilities.
|
|
101
|
+
|
|
102
|
+
The agent read the function's signature and never read the destination's doctrine.
|
|
103
|
+
|
|
104
|
+
**Good: Doctrine-grounded REJECT:**
|
|
105
|
+
|
|
106
|
+
> R1: REJECT. The helpers already in `shared/utils.ts` (`debounce`, `formatBytes`, `clamp`) all share a no-domain-knowledge shape; the file header confirms the invariant with `// Pure, framework-agnostic helpers with no domain knowledge.`. `validateSessionToken` imports `SessionContext` from `auth/types.ts` and decodes a JWT against an auth-specific schema; both violate that invariant, whether read from the surrounding code or from the header. A read of the destination's actual doctrine contradicts the reviewer's "plausibly belongs" framing. The function stays in `auth/validators.ts`.
|
|
107
|
+
|
|
108
|
+
### Bad โ Good: Structural move with destination doctrine satisfied
|
|
109
|
+
|
|
110
|
+
**Review recommendation:** "Move the `MAX_RETRY_COUNT` constant from `network/http-client.ts` to `config/limits.ts`. It's hard-coded near the call site; `config/limits.ts` already holds `MAX_REQUEST_BYTES` and `MAX_CONNECTION_POOL_SIZE`, so grouping operational limits there reduces scatter."
|
|
111
|
+
|
|
112
|
+
**Bad: Reflexive rejection:**
|
|
113
|
+
|
|
114
|
+
> R1: REJECT. Pushback is the default for structural recommendations. The current placement works.
|
|
115
|
+
|
|
116
|
+
The agent invoked the default posture without reading the destination's doctrine to check whether the affirmative-evidence bar is met.
|
|
117
|
+
|
|
118
|
+
**Good: Doctrine-grounded ACCEPT:**
|
|
119
|
+
|
|
120
|
+
> R1: ACCEPT. `config/limits.ts` is the documented home for numeric operational ceilings; its existing members (`MAX_REQUEST_BYTES`, `MAX_CONNECTION_POOL_SIZE`) confirm the category, and `MAX_RETRY_COUNT` shares that exact shape. The constant is currently referenced from three modules that each re-import it from `network/http-client.ts`, a location problem that the original placement created. The destination's stated doctrine accommodates the rule, and the move resolves the duplication; both conditions for the carve-out are met.
|
|
121
|
+
|
|
122
|
+
### Bad โ Good: Deferral-framed recommendation, change does not belong
|
|
123
|
+
|
|
124
|
+
**Review recommendation:** "S1: `memoize` in `utils/memoize.ts` doesn't accept a TTL. Consider a follow-up to add an optional `ttlMs` parameter for time-bounded caching. No action this PR."
|
|
125
|
+
|
|
126
|
+
**Bad: Adopts framing as disposition:**
|
|
127
|
+
|
|
128
|
+
> S1: ACCEPT (follow-up). The reviewer is right that TTL is useful for some cases; we'll create a ticket and defer.
|
|
129
|
+
|
|
130
|
+
The agent took the disposition from the reviewer's handling suggestion and never checked the substance; `ACCEPT (follow-up)` is not a valid disposition.
|
|
131
|
+
|
|
132
|
+
**Good: Substance check, then REJECT:**
|
|
133
|
+
|
|
134
|
+
> S1: REJECT. The file header reads `// Pure memoization keyed on argument identity. For time-bounded caching, use timed-cache.ts.`, and `timed-cache.ts` is the documented home for the exact behavior that the reviewer is suggesting we add. Adding TTL to `memoize` would muddle the two abstractions and break the invariant that the file states explicitly. The change does not belong. The reviewer's "consider a follow-up" framing was a priority signal, not a license to defer the substance question.
|
|
135
|
+
|
|
136
|
+
### Bad โ Good: Deferral-framed recommendation, change belongs (timing decided separately)
|
|
137
|
+
|
|
138
|
+
**Review recommendation:** "T1: `createApiKey` doesn't validate that `scopes` is a non-empty array. Consider a follow-up to add a guard. No action this PR, out of scope for the storage refactor."
|
|
139
|
+
|
|
140
|
+
**Bad: Collapses substance and timing:**
|
|
141
|
+
|
|
142
|
+
> T1: ACCEPT (follow-up). The reviewer is right; we'll create a ticket. Out of scope for this PR.
|
|
143
|
+
|
|
144
|
+
The disposition conflates two decisions: whether the change belongs (substance), and whether it is merged in this PR (timing). `ACCEPT (follow-up)` is not a valid disposition.
|
|
145
|
+
|
|
146
|
+
**Good: Substance check (ACCEPT), then separate timing decision:**
|
|
147
|
+
|
|
148
|
+
> T1: ACCEPT. `createApiKey` is exported from the public `api/keys.ts` surface; the codebase's other public-API entry points (`createUser`, `createOrganization`) all validate their inputs at entry. The missing guard violates the established public-API invariant, so the change belongs. Timing is decided separately: The storage refactor's scope is otherwise tight, and adding the guard pulls in test fixtures unrelated to the refactor's purpose. The guard is added in a follow-up, and the follow-up ticket is filed now (per `create-tickets-immediately` guidance), not kept as a maybe.
|
|
149
|
+
|
|
150
|
+
<!-- include: ../../_partials/comment-discipline.md / -->
|
|
151
|
+
|
|
152
|
+
<!-- include: ../../_partials/diff-audit-checklist.md / -->
|
|
153
|
+
|
|
154
|
+
<!-- guidance-hook: implementation-preferences -->
|
|
155
|
+
|
|
156
|
+
## Writing code after a review
|
|
157
|
+
|
|
158
|
+
Implementing an ACCEPTed finding puts you mid-conversation with the reviewer, which is when that voice enters the comments. A comment must not narrate the change, retell the reviewer's concern, or cite a finding or acceptance-criterion ID.
|
|
159
|
+
|
|
160
|
+
**Before** (narrates the review, cites a finding and an acceptance criterion):
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
// Per F3, the reviewer worried a future refactor could move the toggle to a parent that
|
|
164
|
+
// always renders, silently violating acceptance criterion 4, so pin it here.
|
|
165
|
+
expect(query).not.toHaveProperty('directReportsOnly', true);
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
**After** (states the invariant that the code enforces):
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
// A non-manager viewer emits no directReportsOnly narrowing; the GraphQL surface is the binding contract.
|
|
172
|
+
expect(query).not.toHaveProperty('directReportsOnly', true);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Disposition vocabulary
|
|
176
|
+
|
|
177
|
+
These dispositions express **pre-implementation intent**:
|
|
178
|
+
|
|
179
|
+
- **ACCEPT**: Finding is valid, will implement as recommended
|
|
180
|
+
- **REJECT**: Technically incorrect or intentional choice (must include justification)
|
|
181
|
+
- **PARTIAL**: Some aspects accepted, others pushed back (must specify which)
|
|
182
|
+
|
|
183
|
+
## Disposition scope
|
|
184
|
+
|
|
185
|
+
Per [artifact conventions](../_data/artifact-conventions.md#disposition-rules):
|
|
186
|
+
|
|
187
|
+
| Role | Can disposition | Cannot disposition |
|
|
188
|
+
| -------- | ------------------------------------------------------------ | -------------------------------------------------------- |
|
|
189
|
+
| Coder | Reviewer/overseer findings on the code | Own changes (self-review) |
|
|
190
|
+
| Reviewer | Own prior findings (revise/withdraw in light of new context) | Coder rejections (re-raise as escalated finding instead) |
|
|
191
|
+
| Overseer | Any finding (arbiter authority) | n/a |
|
|
192
|
+
|
|
193
|
+
## Output format
|
|
194
|
+
|
|
195
|
+
When `ticket_ref` is null (the branch does not have a ticket), omit the `{ticket_ref}: ` portion so that the heading reads `# Change summary: {description}`.
|
|
196
|
+
|
|
197
|
+
The artifact begins with YAML frontmatter conforming to the canonical schema; see the canonical example in [artifact-conventions.md](../_data/artifact-conventions.md#universal-artifact-frontmatter) and the field-resolution steps in the [Frontmatter resolution](#frontmatter-resolution) section above. The `responding_to` field is a response-artifact-specific extension that records the review being addressed.
|
|
198
|
+
|
|
199
|
+
The body following the frontmatter has this structure:
|
|
200
|
+
|
|
201
|
+
```markdown
|
|
202
|
+
# Change summary: {ticket_ref}: {description}
|
|
203
|
+
|
|
204
|
+
## Changes made
|
|
205
|
+
|
|
206
|
+
{Summary of code changes made in response to the review, or "No code changes" if responding with dispositions only}
|
|
207
|
+
|
|
208
|
+
## Dispositions
|
|
209
|
+
|
|
210
|
+
### FIXMEs ๐จ
|
|
211
|
+
|
|
212
|
+
#### F1: {title from review}
|
|
213
|
+
|
|
214
|
+
- **Disposition:** ACCEPT | REJECT | PARTIAL
|
|
215
|
+
- **Rationale:** {technical reasoning}
|
|
216
|
+
- **Action taken:** {what the diff does, read back from it, or what subset}
|
|
217
|
+
|
|
218
|
+
### Warnings โ ๏ธ
|
|
219
|
+
|
|
220
|
+
#### W1: {title from review}
|
|
221
|
+
|
|
222
|
+
- **Disposition:** ACCEPT | REJECT | PARTIAL
|
|
223
|
+
- **Rationale:** {technical reasoning}
|
|
224
|
+
- **Action taken:** {what the diff does, read back from it, or what subset}
|
|
225
|
+
|
|
226
|
+
### TODOs ๐
|
|
227
|
+
|
|
228
|
+
#### T1: {title from review}
|
|
229
|
+
|
|
230
|
+
- **Disposition:** ACCEPT | REJECT | PARTIAL
|
|
231
|
+
- **Rationale:** {technical reasoning}
|
|
232
|
+
- **Action taken:** {what the diff does, read back from it, or what subset}
|
|
233
|
+
|
|
234
|
+
### Recommendations ๐ง
|
|
235
|
+
|
|
236
|
+
#### R1: {title from review}
|
|
237
|
+
|
|
238
|
+
- **Disposition:** ACCEPT | REJECT | PARTIAL
|
|
239
|
+
- **Rationale:** {technical reasoning}
|
|
240
|
+
- **Action taken:** {what the diff does, read back from it, or what subset}
|
|
241
|
+
|
|
242
|
+
### Suggestions โ๏ธ
|
|
243
|
+
|
|
244
|
+
#### S1: {title from review}
|
|
245
|
+
|
|
246
|
+
- **Disposition:** ACCEPT | REJECT | PARTIAL
|
|
247
|
+
- **Rationale:** {technical reasoning}
|
|
248
|
+
- **Action taken:** {what the diff does, read back from it, or what subset}
|
|
249
|
+
|
|
250
|
+
### Legacy ๐
|
|
251
|
+
|
|
252
|
+
#### F2-L: {title from review}
|
|
253
|
+
|
|
254
|
+
- **Disposition:** ACCEPT | REJECT
|
|
255
|
+
- **Rationale:** {reasoning}
|
|
256
|
+
|
|
257
|
+
## Summary
|
|
258
|
+
|
|
259
|
+
- Accepted: {count}
|
|
260
|
+
- Rejected: {count}
|
|
261
|
+
- Partial: {count}
|
|
262
|
+
- Implemented in this iteration: {list of IDs}
|
|
263
|
+
- Deferred to follow-up: {list of IDs}
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## Section handling
|
|
267
|
+
|
|
268
|
+
- Code changes summarized under `## Changes made` must themselves satisfy [Comment discipline](#comment-discipline): Comments in the edited code state the code's current contract, not the change history or the reviewer's concern.
|
|
269
|
+
- `Action taken` and `## Changes made` report the diff, read back per [Diff audit](#diff-audit). A disposition asserting that something was left unchanged is a claim about the diff too, and requires the same evidence as one asserting that something changed.
|
|
270
|
+
- Omit category sections that do not contain any findings (e.g., if the review does not contain any TODOs, omit the `### TODOs` section)
|
|
271
|
+
- Preserve the finding IDs exactly as they appear in the review
|
|
272
|
+
- File references in Rationale or Action-taken prose follow the path-format rule in [`review-criteria` ยง Finding references](../review-criteria/SKILL.md#finding-references); use repo-relative paths
|
|
273
|
+
- Legacy findings (IDs with `-L` suffix) use only ACCEPT (acknowledge the observation) or REJECT (disagree with the observation); PARTIAL does not apply
|
|
274
|
+
- If the review does not contain any findings, produce a change summary noting that the review does not contain any findings that require disposition, and omit the Dispositions section
|
|
275
|
+
- A change summary with dispositions only (without code changes) is valid: This is how the coder can close a run by dispositioning all remaining findings
|
|
276
|
+
|
|
277
|
+
## Saving
|
|
278
|
+
|
|
279
|
+
### Path resolution
|
|
280
|
+
|
|
281
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `artifact_base_dir` and `project_slug` from the manifest JSON emitted on stdout (the same invocation in step 1 already populated the manifest file, so this is a fast-path read).
|
|
282
|
+
|
|
283
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
284
|
+
|
|
285
|
+
### Run directory
|
|
286
|
+
|
|
287
|
+
The response is saved as a run artifact: `{timestamp}_coder_change-summary.md`
|
|
288
|
+
|
|
289
|
+
1. Save into the same run directory where the review was found
|
|
290
|
+
2. The timestamp should reflect when this response was produced
|
|
291
|
+
|
|
292
|
+
Dispositions are embedded in this document: The skill does not write a separate disposition artifact.
|