codeassembly-guidance 0.0.0 → 0.2.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 +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- 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 +70 -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 +6 -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 +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -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 +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -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 +19 -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 +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -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 +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -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 +214 -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/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -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/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -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 +180 -0
- package/content/skills/_data/title-templates.md +632 -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/jira-task-list-flattening.md +1 -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 +85 -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/assess-usability/SKILL.md +96 -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 +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -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 +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -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 +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -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 +137 -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 +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -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 +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -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 +148 -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 +71 -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 +317 -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 +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -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 +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -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 +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -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 comments start to repeat the reviewer's wording. 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.
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: review-bb-pr
|
|
3
|
+
description: Fetch Bitbucket PR metadata, verify HEAD, and resolve specification sources for review-pr
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Review Bitbucket pull request
|
|
8
|
+
|
|
9
|
+
Internal delegate that handles the Bitbucket-specific work for `review-pr`: Fetch PR metadata, verify the local HEAD matches the PR's head commit, resolve the ticket (with body-parse fallback), and prepare the spec-source list. Returns a resolved-input record that `review-pr` passes to `review-branch`'s shared review process.
|
|
10
|
+
|
|
11
|
+
This skill does not run a review. The review logic is implemented in `review-branch`.
|
|
12
|
+
|
|
13
|
+
## Delegate interface
|
|
14
|
+
|
|
15
|
+
| Input | Type | Description |
|
|
16
|
+
| -------------------- | -------------- | ------------------------------------------------- |
|
|
17
|
+
| `pr_id` | string | PR number (e.g., `"42"`) or full Bitbucket PR URL |
|
|
18
|
+
| `diff_base_override` | string \| null | `--diff-base` value from `review-pr` if provided |
|
|
19
|
+
| `ticket_override` | string \| null | `--ticket` value from `review-pr` if provided |
|
|
20
|
+
| `project_slug` | string | From session context |
|
|
21
|
+
| `ticket_id` | string \| null | From session context |
|
|
22
|
+
| `artifact_base_dir` | string | From session context |
|
|
23
|
+
|
|
24
|
+
## Resolved-output contract
|
|
25
|
+
|
|
26
|
+
On success, return a record with the same shape as `review-gh-pr`'s output. `review-pr` consumes both delegates' outputs interchangeably:
|
|
27
|
+
|
|
28
|
+
| Field | Type | Description |
|
|
29
|
+
| ---------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| `merge_base_sha` | string | Result of `git merge-base HEAD <diff_base>` |
|
|
31
|
+
| `diff_base` | string | Resolved ref (override if provided, else PR's destination branch) |
|
|
32
|
+
| `spec_sources` | array of `{ source_type, label, content, criteria?, provenance, last_updated }` | One entry per available specification source. Every source is `provenance: "remote"` (this path fetches live and never reads a local snapshot), so the review never renders a divergence note for it; `last_updated` is null when the platform does not expose it (e.g. Jira) |
|
|
33
|
+
| `pr_metadata` | object | `{ number, url, head_oid, base_ref, title }` |
|
|
34
|
+
|
|
35
|
+
On HEAD mismatch, do not return; exit non-zero with the mismatch error. `review-pr` reports the message and stops.
|
|
36
|
+
|
|
37
|
+
## Bitbucket access
|
|
38
|
+
|
|
39
|
+
Make every Bitbucket call below with the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md). That document specifies the tool, the coordinates, the field vocabulary, and the not-connected stop; this skill states only what it does with them.
|
|
40
|
+
|
|
41
|
+
## Process
|
|
42
|
+
|
|
43
|
+
### 1. Normalize `pr_id` and resolve coordinates
|
|
44
|
+
|
|
45
|
+
If `pr_id` is a URL of the form `https://bitbucket.org/{workspace}/{repo}/pull-requests/{number}`, take `{number}` as the PR number.
|
|
46
|
+
|
|
47
|
+
Otherwise treat `pr_id` as the number directly.
|
|
48
|
+
|
|
49
|
+
Resolve `workspaceId` and `repoId` per [Coordinates](../_data/bitbucket-pr-access.md#coordinates), which takes them from the `pr_id` URL when it is one.
|
|
50
|
+
|
|
51
|
+
### 2. Fetch PR metadata
|
|
52
|
+
|
|
53
|
+
Issue a single `action: "get"` call with `prId` set to the PR number, per [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request). Capture `id`, `title`, `description`, `links.html.href`, `updated_on`, `source.branch.name`, `source.commit.hash`, and `destination.branch.name`.
|
|
54
|
+
|
|
55
|
+
If the call fails, report the tool's error and stop.
|
|
56
|
+
|
|
57
|
+
### 3. Verify HEAD
|
|
58
|
+
|
|
59
|
+
Compare the local HEAD against the PR's head commit:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git rev-parse HEAD
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The comparison is a prefix test, not an equality test, because the tool may return `source.commit.hash` abbreviated; see [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request) for the rule. If `source.commit.hash` is not a prefix of the printed HEAD of at least 7 characters, exit non-zero with:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
PR #{number}'s head commit is {short(source_commit_hash)} but HEAD is at {short(HEAD)}. Check out the PR branch first (e.g., "git fetch origin pull-requests/{number}/from:pr-{number} && git checkout pr-{number}") or pull the latest commits on {source_branch_name}.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Use the first 7 characters for short SHAs. **Fail closed**: Never proceed with mismatched state.
|
|
72
|
+
|
|
73
|
+
### 4. Resolve the diff base
|
|
74
|
+
|
|
75
|
+
Apply this cascade:
|
|
76
|
+
|
|
77
|
+
1. If `diff_base_override` is non-null, use it.
|
|
78
|
+
2. Otherwise, use `destination.branch.name` from PR metadata.
|
|
79
|
+
|
|
80
|
+
Compute the merge-base once:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
git merge-base HEAD {diff_base}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### 5. Resolve the ticket
|
|
87
|
+
|
|
88
|
+
**Bitbucket linked-issues divergence from GitHub.** Bitbucket Cloud's PR API does not expose a structured `closingIssuesReferences` field equivalent to GitHub's. (Bitbucket has a separate Issues product with linked-issue support, but its surface differs and is not always enabled per workspace.) Rather than introducing a partial linked-issues mechanism here, this delegate uses a simpler cascade:
|
|
89
|
+
|
|
90
|
+
1. **`ticket_override`**: If non-null, resolve per [ticket source resolution](../_data/ticket-source-resolution.md) and use it.
|
|
91
|
+
2. **Parse PR body for issue references**: Scan `description` for the first match of any of these patterns (case-insensitive):
|
|
92
|
+
- `closes #{n}`, `closes: #{n}`
|
|
93
|
+
- `fixes #{n}`, `fixes: #{n}`
|
|
94
|
+
- `resolves #{n}`, `resolves: #{n}`
|
|
95
|
+
- bare `#{n}`
|
|
96
|
+
- Jira-style keys (e.g., `MAC-42`) when the project's `ticket_ref_prefix` is configured to a Jira prefix.
|
|
97
|
+
|
|
98
|
+
Fetch the matched issue per [ticket source resolution](../_data/ticket-source-resolution.md).
|
|
99
|
+
|
|
100
|
+
3. **No ticket**: Proceed with the PR description as the only spec source.
|
|
101
|
+
|
|
102
|
+
The divergence from `review-gh-pr` is intentional and documented here so that future readers do not assume parity. If Bitbucket linked-issue parity is added later (via the Jira integration or a future Bitbucket API field), a new step fits between override and body parse without breaking the delegate interface.
|
|
103
|
+
|
|
104
|
+
### 6. Build the spec-source list
|
|
105
|
+
|
|
106
|
+
Always include the PR description as a source:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
{
|
|
110
|
+
source_type: "pr_description",
|
|
111
|
+
label: "pr_description: PR #{number}",
|
|
112
|
+
content: <description>,
|
|
113
|
+
criteria: <optional: extracted from `## What`, `## Summary`, or an explicit acceptance-criteria heading>,
|
|
114
|
+
provenance: "remote",
|
|
115
|
+
last_updated: <PR `updated_on`>
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
If a ticket was resolved in step 5, prepend it:
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
{
|
|
123
|
+
source_type: "ticket",
|
|
124
|
+
label: "ticket: {ticket_ref or short identifier}",
|
|
125
|
+
content: <ticket body>,
|
|
126
|
+
criteria: <optional: extracted from the ticket structure>,
|
|
127
|
+
provenance: "remote",
|
|
128
|
+
last_updated: <ticket last-updated when the platform exposes it (GitHub `updatedAt`); null when it does not (e.g. Jira)>
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The list order is `[ticket?, pr_description]`, same as `review-gh-pr`.
|
|
133
|
+
|
|
134
|
+
### 7. Return the resolved-output record
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
{
|
|
138
|
+
merge_base_sha: <from step 4>,
|
|
139
|
+
diff_base: <from step 4>,
|
|
140
|
+
spec_sources: <from step 6>,
|
|
141
|
+
pr_metadata: {
|
|
142
|
+
number: <id>,
|
|
143
|
+
url: <links.html.href>,
|
|
144
|
+
head_oid: <the HEAD printed in step 3>,
|
|
145
|
+
base_ref: <destination.branch.name>,
|
|
146
|
+
title: <title>
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`head_oid` contains the local HEAD rather than `source.commit.hash`, which step 3 may have matched abbreviated. The two name the same commit once step 3 passes, and the local one is the full 40 characters expected by a consumer of an OID.
|
|
152
|
+
|
|
153
|
+
`review-pr` passes this to `review-branch` and the review proceeds.
|
|
154
|
+
|
|
155
|
+
## Important
|
|
156
|
+
|
|
157
|
+
- **Single read for metadata.** All fields are fetched at once. Do not split into multiple calls.
|
|
158
|
+
- **The REST pin is no longer needed.** This delegate used to pin the REST API because a generic "whatever tooling is available" instruction could not guarantee that a client returned `source.commit.hash`, which the _Verify HEAD_ step fails closed on. Naming one tool removes that reason, and the field is verified present in its response. Do not restore the credential cascade or the REST endpoint because of the old comment.
|
|
159
|
+
- **HEAD mismatch is a hard stop.** The error message must include a Bitbucket-equivalent checkout suggestion so that the user has a one-line fix path even though Bitbucket lacks `gh pr checkout`'s exact equivalent.
|
|
160
|
+
- **Linked-issues divergence is intentional.** The Bitbucket cascade lacks the GitHub `closingIssuesReferences` step. This is documented above so that the parity gap is visible to future readers; do not silently re-add a partial implementation.
|
|
161
|
+
- **No review logic here.** This delegate prepares inputs only. The review process runs inside `review-branch` after `review-pr` invokes it with the resolved inputs.
|