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,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: review-permissions
|
|
3
|
+
description: Use at end of session to recommend updates to the Claude Code permissions allow list based on commands used
|
|
4
|
+
user-invocable: true
|
|
5
|
+
supported-harnesses: [claude]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Review permissions
|
|
9
|
+
|
|
10
|
+
Recommend modifications to `~/.claude/settings.json` permissions based on commands used in this session.
|
|
11
|
+
|
|
12
|
+
## Process
|
|
13
|
+
|
|
14
|
+
1. **Read current settings** from `~/.claude/settings.json` → `permissions`
|
|
15
|
+
2. **Review commands executed** in this session
|
|
16
|
+
3. **Identify gaps**: Commands that needed manual approval or were missing from the list
|
|
17
|
+
4. **Recommend additions**, following the consolidation strategy below
|
|
18
|
+
5. **Check deny list**: Do not recommend additions that conflict with `permissions.deny`
|
|
19
|
+
6. **Output a proposed diff** to `settings.json`
|
|
20
|
+
|
|
21
|
+
## Current strategy
|
|
22
|
+
|
|
23
|
+
The permissions use `acceptEdits` mode + consolidated allowlist + deny list:
|
|
24
|
+
|
|
25
|
+
- **`acceptEdits` mode** (`defaultMode: "acceptEdits"`) auto-approves all file operations (Read, Edit, Write). This eliminates file-modification confirmation prompts. The worktree-based workflow makes this safe: Every branch is trivially revertible.
|
|
26
|
+
- **Bash allowlist** uses broad prefix patterns (`Bash(git:*)`) rather than individual subcommand entries (`Bash(git add:*)`, `Bash(git commit:*)`, etc.). One wildcard per tool family.
|
|
27
|
+
- **Deny list** blocks destructive patterns that the broad allowlist would otherwise permit. This is the primary safety mechanism for Bash commands.
|
|
28
|
+
|
|
29
|
+
## Guidance for recommendations
|
|
30
|
+
|
|
31
|
+
- **Prefer the broadest safe pattern.** `Bash(docker:*)` over listing individual subcommands.
|
|
32
|
+
- **When adding a broad pattern, check for destructive subcommands** that need deny list entries. For example, `Bash(git:*)` requires `Bash(git checkout .)`, `Bash(git clean:*)`, `Bash(git reset --hard:*)`, etc. in the deny list.
|
|
33
|
+
- **Do not recommend Edit or Read rules**: `acceptEdits` mode covers all file operations. Read rules in the allow list only serve as explicit documentation for paths outside the working directory.
|
|
34
|
+
- **Never recommend allowing commands that are destructive by nature** (rm -rf, git push --force, git reset --hard): These belong in the deny list.
|
|
35
|
+
- **Note any commands that the user approved manually** and that seem intentionally ungated (one-off operations).
|
|
36
|
+
|
|
37
|
+
## Limitations
|
|
38
|
+
|
|
39
|
+
A formal approval log is not available to this skill. Recommendations are based on commands executed in this session and the agent's memory of permission prompts. Invoke this skill while the conversation context is fresh.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: review-pr
|
|
3
|
+
description: Review a pull request by detecting the platform, fetching PR metadata via a delegate, and running the shared branch-review process
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Review pull request
|
|
8
|
+
|
|
9
|
+
Review a pull request on the appropriate platform. Detects the platform, dispatches to a delegate (`{skill:review-gh-pr}` or `{skill?:review-bb-pr}`) that fetches PR metadata, verifies HEAD matches the PR's head commit, and resolves specification sources, then invokes the shared review process from `{skill:review-branch}` with the resolved inputs.
|
|
10
|
+
|
|
11
|
+
This is a thin entry skill: The shared review logic (diff analysis, finding generation, "Specification compliance" rendering, artifact saving) is implemented in `review-branch`. Delegates own only the platform-specific work (PR-metadata fetch, HEAD verification, ticket resolution from PR linked issues, PR-description preparation). After the delegate returns its resolved inputs, this skill invokes `review-branch`'s review process with the prepared spec-source list and resolved diff base.
|
|
12
|
+
|
|
13
|
+
## Arguments
|
|
14
|
+
|
|
15
|
+
| Argument | Description | Default |
|
|
16
|
+
| ------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
|
17
|
+
| `<pr_id>` | Positional. Full GitHub or Bitbucket PR URL, or a bare PR number. An explicit value always overrides the stored URL. | _(required unless a stored `pr_url` exists in the manifest)_ |
|
|
18
|
+
| `--diff-base=<ref>` | Override the diff base. Reviews `merge-base(HEAD, <ref>)..HEAD`. | The PR's `baseRefName` (or Bitbucket equivalent) |
|
|
19
|
+
| `--ticket=<source>` | Override the auto-resolved ticket. Resolved per [ticket source resolution](../_data/ticket-source-resolution.md). | PR's first linked issue, then PR-body parse, then none |
|
|
20
|
+
|
|
21
|
+
## Process
|
|
22
|
+
|
|
23
|
+
### 1. Get session context
|
|
24
|
+
|
|
25
|
+
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 `project_slug`, `ticket_id`, `ticket_ref`, `default_branch`, `artifact_base_dir`, `scm`, and `pr_url` from it. Pass these values into `review-branch`'s steps 4–9 (review header, scoring, saving) so that `review-branch`'s own step 1 does not need to re-run.
|
|
26
|
+
|
|
27
|
+
### 2. Resolve the PR
|
|
28
|
+
|
|
29
|
+
Resolve the PR to review per [PR source resolution](../_data/pr-source-resolution.md#runtime-resolution-path-add-change-record-review-pr-merge-pr): An explicit `<pr_id>` overrides; otherwise a stored `pr_url` from session context is the default; otherwise discover the PR for the current branch. Persist the resolved URL via `--set-pr-url`, and invalidate (`--clear-pr-url`) and re-resolve a stored URL that does not yield the expected PR. The resolved value is passed to the delegate as `pr_id` in step 5.
|
|
30
|
+
|
|
31
|
+
### 3. Detect platform
|
|
32
|
+
|
|
33
|
+
Apply the [platform resolution cascade](../_data/ticket-source-resolution.md#platform-resolution-cascade):
|
|
34
|
+
|
|
35
|
+
1. Check `.agents/preferences.yaml` → `integrations` (if exactly one is enabled, use it; if multiple, ask).
|
|
36
|
+
2. Check `git remote get-url origin` (`github.com` → GitHub; `bitbucket.org` → Bitbucket).
|
|
37
|
+
3. Ask the user.
|
|
38
|
+
|
|
39
|
+
If `<pr_id>` is a full URL, the URL host overrides the cascade: A `https://github.com/...` URL is GitHub regardless of preferences. Numeric `<pr_id>` inputs use the cascade-resolved platform.
|
|
40
|
+
|
|
41
|
+
### 4. Select delegate
|
|
42
|
+
|
|
43
|
+
| Platform | Delegate |
|
|
44
|
+
| ------------------------- | -------------- |
|
|
45
|
+
| `github` | `review-gh-pr` |
|
|
46
|
+
| `bitbucket` | `review-bb-pr` |
|
|
47
|
+
| Unknown after the cascade | Ask the user |
|
|
48
|
+
|
|
49
|
+
### 5. Call delegate
|
|
50
|
+
|
|
51
|
+
Pass the following inputs to the selected delegate per its delegate interface:
|
|
52
|
+
|
|
53
|
+
| Input | Value |
|
|
54
|
+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| `pr_id` | The PR resolved in step 2. The delegate parses and normalizes it (extracts the PR number from a URL when applicable; the Bitbucket delegate also resolves the workspace and repository that it addresses). |
|
|
56
|
+
| `diff_base_override` | Value of `--diff-base` if provided; otherwise `null` |
|
|
57
|
+
| `ticket_override` | Value of `--ticket` if provided; otherwise `null` |
|
|
58
|
+
| `project_slug` | From session context |
|
|
59
|
+
| `ticket_id` | From session context |
|
|
60
|
+
| `artifact_base_dir` | From session context |
|
|
61
|
+
|
|
62
|
+
The delegate returns a resolved-input record:
|
|
63
|
+
|
|
64
|
+
| Field | Type | Description |
|
|
65
|
+
| ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
66
|
+
| `merge_base_sha` | string | Result of `git merge-base HEAD <diff-base>` after delegate-side resolution |
|
|
67
|
+
| `diff_base` | string | The ref against which the delegate resolved |
|
|
68
|
+
| `spec_sources` | array of `{ source_type, label, content, criteria?, provenance, last_updated }` | One entry per available specification source. `provenance`/`last_updated` are recorded so that the review can state which contract it measured against; delegate-supplied sources are always `provenance: "remote"` |
|
|
69
|
+
| `pr_metadata` | object (PR number, URL, head SHA, base ref, title) | Used by the review heading |
|
|
70
|
+
|
|
71
|
+
If the delegate exits with a HEAD-mismatch error (the PR's head commit is not the local HEAD), report its error message and stop. Do not proceed with mismatched state.
|
|
72
|
+
|
|
73
|
+
### 6. Invoke the shared review process
|
|
74
|
+
|
|
75
|
+
Invoke `review-branch`'s review process with the resolved inputs:
|
|
76
|
+
|
|
77
|
+
- The diff base is `merge_base_sha` (already computed by the delegate).
|
|
78
|
+
- The spec-source list is `spec_sources` from the delegate. The "Specification compliance" section in the review output renders one subsection per entry. For a typical PR, this list contains both the ticket (when one was resolved) and the PR description as a `pr_description` source.
|
|
79
|
+
- The review heading uses `pr_metadata` to show the PR number and URL alongside the ticket reference.
|
|
80
|
+
|
|
81
|
+
Invoke `review-branch`'s [Process](../review-branch/SKILL.md#process) starting at step 4 (read prior artifacts). Steps 1–3 of `review-branch` are already complete: Session context was gathered in step 1 above; `merge_base_sha` and `spec_sources` were resolved by the delegate.
|
|
82
|
+
|
|
83
|
+
### 7. Save and present next steps
|
|
84
|
+
|
|
85
|
+
`review-branch`'s saving and next-steps logic apply unchanged. The review artifact is saved into the ticket's active run directory.
|
|
86
|
+
|
|
87
|
+
Because this review covers a pull request, the next-steps Findings sub-block renders its PR variant: "Post findings on the PR" rather than the local-branch options. The Source-divergence sub-block likewise appears here whenever the PR description and ticket diverge, since both spec sources are present.
|
|
88
|
+
|
|
89
|
+
## Examples
|
|
90
|
+
|
|
91
|
+
### Review the PR for the current branch
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# Check out the PR branch first, then review it.
|
|
95
|
+
gh pr checkout 1024
|
|
96
|
+
{skill:review-pr} 1024
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Review a PR by URL
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
gh pr checkout https://github.com/williamthorsen/codeassembly/pull/1024
|
|
103
|
+
{skill:review-pr} https://github.com/williamthorsen/codeassembly/pull/1024
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Review a stacked PR with a non-default diff base
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
gh pr checkout 1024
|
|
110
|
+
{skill:review-pr} 1024 --diff-base=feature/parent-branch
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Override the auto-resolved ticket
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
{skill:review-pr} 1024 --ticket=#553
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Important
|
|
120
|
+
|
|
121
|
+
- **Always check out the PR first.** The delegate compares `git rev-parse HEAD` to the PR's head commit and fails closed if they differ. The error message includes the platform-specific checkout command (e.g., `gh pr checkout <n>`).
|
|
122
|
+
- **The orchestrator does not own any review logic.** All findings, scoring, and the "Specification compliance" rendering happen inside `review-branch`. This skill is platform detection + delegate dispatch + invocation of the shared review process.
|
|
123
|
+
- **Two specification sources by default.** Unlike `{skill:review-branch}` (one source: the ticket), `{skill:review-pr}` adds the PR description as a second source so that the review evaluates the implementation against both. Source-vs-source divergence is reported in the `## Specification consistency` section of the review output (see `review-branch/SKILL.md`).
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: revise-comments
|
|
3
|
+
description: Revise comments in target files per the comment-discipline rules, adding missing code descriptions and fixing drifted ones, editing in place
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Revise comments
|
|
8
|
+
|
|
9
|
+
Apply the comment-discipline audit to a target file set, editing comments in place: Keep, delete, or rewrite each comment, add a description to each declaration that lacks one, and rewrite each description that misstates its code. The default workflow is `{skill:revise-comments}` after a feature is implemented; explicit paths support cleaning up legacy code.
|
|
10
|
+
|
|
11
|
+
If the `revise-prose` sweep is wanted on the same files, run this skill first: It decides whether a comment exists at all, and it may delete the very comment that the prose sweep would otherwise polish.
|
|
12
|
+
|
|
13
|
+
## Invocation
|
|
14
|
+
|
|
15
|
+
- `{skill:revise-comments}`: Default target is files committed on the current branch relative to the default branch. To audit uncommitted work, pass explicit paths (`{skill:revise-comments} .` covers the working tree).
|
|
16
|
+
- `{skill:revise-comments} <path> [<path>...]`: Explicit file or directory targets. Directories are processed recursively.
|
|
17
|
+
- `{skill:revise-comments} --dry-run [...]`: Produce the summary without applying edits. Triage and dry-run are unified under this flag.
|
|
18
|
+
|
|
19
|
+
## Process
|
|
20
|
+
|
|
21
|
+
1. **Resolve the target file set** per [Target file set](#target-file-set), keeping the comment-supporting files from what it yields.
|
|
22
|
+
|
|
23
|
+
Without an argument, the target is the set of files changed in commits on the current branch relative to the default branch. Obtain `{default_branch}` via `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`, then:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
git diff --name-only "{default_branch}...HEAD"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
2. **Apply the audit per file.** Read each target file. Put every comment through the tests below, and every declaration through [Description coverage and accuracy](#description-coverage-and-accuracy). Decide one of four actions: kept, deleted, rewritten, or added. In normal mode, apply edits in place via the Edit tool. In `--dry-run` mode, record the proposed action without editing.
|
|
30
|
+
|
|
31
|
+
3. **Audit the diff** per [Diff audit](#diff-audit), over the edits just applied. A re-worded comment is the reach sweep's central case: It can invalidate a sibling doc, a README, or a test title that echoed the phrasing that it replaced. Such a file is outside the resolved target set, so the hard gate in [Target file set](#target-file-set) applies: Report the hit to the user alongside the summary rather than repair it. Because `--dry-run` does not apply any edits, the step is skipped under that flag.
|
|
32
|
+
|
|
33
|
+
4. **Emit the summary.** After processing all targets, emit one table per file with non-trivial decisions.
|
|
34
|
+
|
|
35
|
+
<!-- include: ../../_partials/target-file-set-resolution.md / -->
|
|
36
|
+
|
|
37
|
+
<!-- include: ../../_partials/comment-discipline.md / -->
|
|
38
|
+
|
|
39
|
+
<!-- include: ../../_partials/diff-audit-checklist.md / -->
|
|
40
|
+
|
|
41
|
+
## Description coverage and accuracy
|
|
42
|
+
|
|
43
|
+
Because the baseline above requires a description, this skill acts on declarations as well as on the comments that they have:
|
|
44
|
+
|
|
45
|
+
- **Coverage.** Add a description (`added`) to each function, method, class, and component that lacks one, helpers in test files included. Skip an anonymous callback passed inline, which is not a declaration. Do not add one to a constant or a type, for which the baseline makes a description optional.
|
|
46
|
+
- **Accuracy.** Compare each description with the code that it describes, and rewrite one that misstates what the code does or is. Length alone is not a reason to rewrite an accurate description.
|
|
47
|
+
- **Never deleted.** Rewrite a declaration's description that fails one of the four tests; never delete it, because the baseline requires one.
|
|
48
|
+
- **Form.** Write an added or rewritten description in the doc-comment form that the file already uses, or else in the language's standard form, such as JSDoc in TypeScript.
|
|
49
|
+
|
|
50
|
+
## File-level carve-outs
|
|
51
|
+
|
|
52
|
+
The carve-outs above apply to comments. Two file-level rules decide which lines this skill may touch at all:
|
|
53
|
+
|
|
54
|
+
- **Test files.** Path contains `__tests__/` or filename matches `*.spec.*` / `*.test.*`. The test-comment carve-out applies inside them; the tests still apply to everything else in the file.
|
|
55
|
+
- **`eslint-disable` lines.** Lines beginning with `eslint-disable`, `eslint-disable-next-line`, `eslint-disable-line`, or the block forms `/* eslint-disable */` and `/* eslint-enable */`. Keep the rationale, tightened to name only why the rule is suppressed at that line. Strip surrounding context, ticket references, and design discussion.
|
|
56
|
+
|
|
57
|
+
## When to pause and ask
|
|
58
|
+
|
|
59
|
+
The default is to act. Pause and ask the user when one of these holds:
|
|
60
|
+
|
|
61
|
+
- A test comment could plausibly be non-obvious setup, but the test name already conveys the setup intent.
|
|
62
|
+
- An `eslint-disable` rationale is at the boundary between tight and over-scoped.
|
|
63
|
+
- A file header describes potentially load-bearing architecture (composition order, threading model, invariants across functions), so it may state a constraint that the code cannot show.
|
|
64
|
+
- A description and its code disagree, and the code could be the part that is wrong, such as when the declaration's name agrees with the description. Rewriting the description would record the defect as intended behavior, and this skill never edits code.
|
|
65
|
+
|
|
66
|
+
## Summary format
|
|
67
|
+
|
|
68
|
+
After processing, emit one Markdown table per file. Skip files with zero decisions. The same format appears in normal and `--dry-run` runs; in dry-run mode, append `(dry-run)` to the heading.
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
revise-comments summary
|
|
72
|
+
|
|
73
|
+
src/lib/payload.ts
|
|
74
|
+
| Line | Action | Test | Reason |
|
|
75
|
+
| ---- | --------- | ------------ | -------------------------------- |
|
|
76
|
+
| 1 | deleted | one-location | duplicates the per-function docs |
|
|
77
|
+
| 2 | deleted | stranger | PR reference |
|
|
78
|
+
| 4 | rewritten | stranger | "we discussed" |
|
|
79
|
+
| 6 | kept | n/a | why-inline |
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`Test` names the test that decided the action: one of the four, `accuracy`, `baseline` for an added description, or `n/a`. For `added`, `Line` is the declaration's line.
|
|
83
|
+
|
|
84
|
+
Line numbers refer to the pre-edit file, so check each row against `git diff` output before emitting the table: The `Action` column reports what the diff shows, not what was intended. For a comment failing more than one test, report the first that it fails.
|
|
85
|
+
|
|
86
|
+
## Worked example
|
|
87
|
+
|
|
88
|
+
A small file demonstrating multi-comment revision end-to-end.
|
|
89
|
+
|
|
90
|
+
**Before** (`src/lib/payload.ts`):
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
// Helpers for building the request payload sent to the orchestrator API.
|
|
94
|
+
// Originally added in PR #423 to consolidate the type narrowing logic.
|
|
95
|
+
|
|
96
|
+
// Builds the canonical payload shape. We discussed inlining but it's used at three call sites.
|
|
97
|
+
export function buildPayload(input: Input): Payload {
|
|
98
|
+
// react-select types value as a union; narrow to array.
|
|
99
|
+
const items = Array.isArray(input.value) ? input.value : [input.value];
|
|
100
|
+
return { items };
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** Returns the first item, or undefined when the payload is empty. */
|
|
104
|
+
export function lastItem(payload: Payload): Item | undefined {
|
|
105
|
+
return payload.items.at(-1);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export function isEmptyPayload(payload: Payload): boolean {
|
|
109
|
+
return payload.items.length === 0;
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
**After:**
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
/** Builds the canonical payload shape. */
|
|
117
|
+
export function buildPayload(input: Input): Payload {
|
|
118
|
+
// react-select types value as a union; narrow to array.
|
|
119
|
+
const items = Array.isArray(input.value) ? input.value : [input.value];
|
|
120
|
+
return { items };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Returns the last item, or undefined when the payload is empty. */
|
|
124
|
+
export function lastItem(payload: Payload): Item | undefined {
|
|
125
|
+
return payload.items.at(-1);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Reports whether the payload has no items. */
|
|
129
|
+
export function isEmptyPayload(payload: Payload): boolean {
|
|
130
|
+
return payload.items.length === 0;
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
**Summary emitted:**
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
revise-comments summary
|
|
138
|
+
|
|
139
|
+
src/lib/payload.ts
|
|
140
|
+
| Line | Action | Test | Reason |
|
|
141
|
+
| ---- | --------- | ------------ | -------------------------------- |
|
|
142
|
+
| 1 | deleted | one-location | duplicates the per-function docs |
|
|
143
|
+
| 2 | deleted | stranger | PR reference |
|
|
144
|
+
| 4 | rewritten | stranger | "we discussed" |
|
|
145
|
+
| 6 | kept | n/a | why-inline |
|
|
146
|
+
| 11 | rewritten | accuracy | says first; code returns last |
|
|
147
|
+
| 16 | added | baseline | no description |
|
|
148
|
+
```
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: revise-prose
|
|
3
|
+
description: Sweep a repository's prose against the writing rule set, repair it through dispatched subagents, and record what was swept
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Revise prose
|
|
8
|
+
|
|
9
|
+
Sweep a repository's prose against the rules below, repair every clear site, and record what the repository has now been swept for. A bundled helper does the mechanical half: It resolves which files may be swept, extracts their prose, reports over-inclusive candidates, and packs the files into batches. You do the dispatching half: one `{subagent:prose-reviser}` subagent per batch, one commit per batch, and one closing pass over what the subagents would not decide alone.
|
|
10
|
+
|
|
11
|
+
Apply is the default. `--dry-run` produces the report alone.
|
|
12
|
+
|
|
13
|
+
**Announce at start:** "Using revise-prose to {report on | revise} prose in {the repository | the given paths}."
|
|
14
|
+
|
|
15
|
+
## Arguments
|
|
16
|
+
|
|
17
|
+
| Argument | Description | Required |
|
|
18
|
+
| ------------------------ | ------------------------------------------------------------------------------- | -------- |
|
|
19
|
+
| `<path>` | One or more files or directories narrowing the sweep. Repeatable. | No |
|
|
20
|
+
| `--batch-budget <bytes>` | Ceiling on a batch's combined file bytes. Passed to the helper unchanged. | No |
|
|
21
|
+
| `--dry-run` | Report and stop without dispatching a subagent, editing, or writing the record. | No |
|
|
22
|
+
| `--rule <id>` | One rule that this document declares, narrowing the sweep. Repeatable. | No |
|
|
23
|
+
|
|
24
|
+
Without a path, the sweep covers the whole repository. That is this skill's default, because removing every violation from a repository requires a full sweep. It is how this skill differs from `{skill:revise-comments}`, whose default is the current branch's diff.
|
|
25
|
+
|
|
26
|
+
`--rule` takes a rule's id as step 1 derives it, not a unit's name: `--rule plain-speech` sweeps the rule `plain-speech` without the rules that its calibration declares.
|
|
27
|
+
|
|
28
|
+
## Ordering with `revise-comments`
|
|
29
|
+
|
|
30
|
+
`{skill:revise-comments}` decides whether a comment exists and what it may say. This skill decides how a span of prose reads, and it never adds, deletes, or shortens a comment. If both are wanted on the same files, run `{skill:revise-comments}` first: It may delete the very comment that this sweep would otherwise polish.
|
|
31
|
+
|
|
32
|
+
## Process
|
|
33
|
+
|
|
34
|
+
### 1. Read the units and the rules from this document
|
|
35
|
+
|
|
36
|
+
Both come from this document, never from a list kept elsewhere. Because a rule document declares each rule by a marker beside it rather than by its heading, a heading change cannot silently drop a rule, and a project bound to a different rulebook is swept for the rules that it declares.
|
|
37
|
+
|
|
38
|
+
- **The `plain-speech` unit** is at the version that the `<!-- unit-version: plain-speech <version> -->` marker below names. It contains the rule `plain-speech`, whose sweep version is the same, and each rule that a `<!-- rule: <id> <version> -->` marker in its calibration below declares, at that marker's sweep version.
|
|
39
|
+
- **Each `<!-- rulebook:<slug> -->` block** in the comment-preferences and writing-preferences fills at the end of this document is a unit, at the version that its `<!-- rulebook-version: <version> -->` line names. A block that does not specify a version is not a unit: Do not name its rules to the helper, sweep it without recording anything for it, and name that slug in the closing summary.
|
|
40
|
+
- **Each `<!-- rule: <id> <version> -->` marker** in a unit's body declares a rule at that sweep version, whether or not the helper has a detector for it. The rule's unit is the block containing the marker.
|
|
41
|
+
- **A marker that reads `<!-- rule: <id> -->`** declares a rule without a sweep version. It is swept, but nothing records it: Name it to the helper without a version, and name it in the closing summary.
|
|
42
|
+
- **A rule heading without a marker beneath it** does not declare an id or a sweep version. Its id is the heading's text lowercased, with backticks dropped, each run of characters other than letters and digits replaced by one hyphen, and hyphens trimmed from both ends; its unit is the block containing the heading. Do not name it to the helper, and name it in the closing summary.
|
|
43
|
+
|
|
44
|
+
**The unrecorded rules** are the rules that nothing records: each marker without a sweep version, each heading without a marker, and each rule in a block that is not a unit, whose id is its marker's id or, without a marker, its heading's id derived as above. Keep their ids for step 4, which dispatches them with every batch.
|
|
45
|
+
|
|
46
|
+
The record keys coverage and rejections on each rule's sweep version. A unit's version is passed only to convert a record written before rules had versions.
|
|
47
|
+
|
|
48
|
+
If the fills are empty, nothing is bound here: The run sweeps `plain-speech` alone.
|
|
49
|
+
|
|
50
|
+
**Narrow to the named rules.** Without `--rule`, keep every rule that this step declares. With it, first check each named id against the ids that this step declares, the ids derived from headings included; if one is not among them, stop the run before the helper runs, and name that id. Then keep only the named rules, versioned and unrecorded alike, and keep every unit. Every later step works from the rules that this step kept, and the closing summary does not name any other rule.
|
|
51
|
+
|
|
52
|
+
### 2. Run the sweep
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
node {harness_home_dir}/skills/revise-prose/revise-prose.mjs detect {paths} \
|
|
56
|
+
--unit plain-speech={version} \
|
|
57
|
+
--rule plain-speech@{version}=plain-speech \
|
|
58
|
+
--rule {calibration-rule-id}@{rule-version}=plain-speech \
|
|
59
|
+
--unit {slug}={version} \
|
|
60
|
+
--rule {rule-id}@{rule-version}={slug} \
|
|
61
|
+
--rule {unversioned-rule-id}={slug}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Pass one `--unit` per unit from step 1, and one `--rule` per rule that step 1 kept: `--rule plain-speech@{version}=plain-speech` for `plain-speech`, `--rule {id}@{rule-version}={unit}` for a rule whose marker declares a version, and `--rule {id}={unit}` for a rule whose marker declares none. Pass nothing for a rule that does not have a marker or whose block is not a unit, as step 1 directs. Add `--batch-budget {bytes}` if the invocation included one. Omit the paths for a whole-repository sweep.
|
|
65
|
+
|
|
66
|
+
The helper prints one JSON object to stdout. On success it contains `ok: true`, the `root` that it swept, a `candidates` array, a `rejections` array containing the sites already adjudicated by an earlier sweep, a `batches` array in which each batch lists as `unswept` the versioned rules that its files still need, a `rules` object listing the named rules that it `detected` and those for which it does not have a detector as `undetected`, and a `summary`. On failure it contains `ok: false` with `invalid-args`, `invalid-record`, or `not-a-repository`, the last because the sweep reads what git tracks and has nothing to read outside a working tree. Report a failure and stop.
|
|
67
|
+
|
|
68
|
+
Read `summary` before anything else. `filesSkipped` counts the files that the sweep excluded, keyed by the reason for each: `generated` and `machine-generated` for output whose edit belongs to its source, `vendored` for a verbatim extract whose edit belongs to the project from which it was extracted, `unreadable` for a file whose prose cannot be read, and `ineligible` for one not read by any extractor. `batchesSkipped` counts the batches that the record already covers; `stale` counts the candidates whose recorded rejection was taken at an older version of its rule.
|
|
69
|
+
|
|
70
|
+
`candidates` and `rejections` contain only the sites in the reported batches' files, under a rule that the batch lists as `unswept` or, for a candidate, under a rule named without a version.
|
|
71
|
+
|
|
72
|
+
An empty `batches` array ends the run: Report the summary in one line and stop. The repository is already swept at every versioned rule's current version.
|
|
73
|
+
|
|
74
|
+
**Under `--dry-run`, the run ends here.** Emit the summary and one candidate table per file, per [Summary format](#summary-format), and stop. Do not dispatch a subagent, do not write a record, and edit nothing. A dry run takes one helper run, whereas a report-then-apply pair would run the sweep twice.
|
|
75
|
+
|
|
76
|
+
**An apply run needs a clean tree.** If `git status --porcelain` reports anything, stop and report it. Because step 4's gate reads `git diff --name-only` as the wave's own work, an edit already in the tree either trips that gate or, if it is inside a batch's file list, is committed with that batch under the sweep's message. A dry run ends before this check and edits nothing; therefore, this stop holds only for an apply run.
|
|
77
|
+
|
|
78
|
+
### 3. Pilot the first batch
|
|
79
|
+
|
|
80
|
+
Run the pilot if `.agents/revise-prose.yaml` is absent, or if it names none of this run's versioned rules under `rules:` and none of its units under `units:`. A rerun skips this step and goes to step 4.
|
|
81
|
+
|
|
82
|
+
Dispatch batch 0 alone, per step 4's dispatch shape, and run step 4's checks over it as a wave of one. Accumulate its `rejected` and `questionable` entries for step 5, as step 4 directs for every later wave, so that the pilot's questionables appear in the closing table. Then show the user its report and `git diff --stat`, and ask for a go-ahead before committing that batch and before dispatching anything else.
|
|
83
|
+
|
|
84
|
+
On a no-go, ask the user before reverting, then revert that batch's files and stop. A miscalibrated subagent is worth catching once per repository, which is the whole reason the first batch runs alone.
|
|
85
|
+
|
|
86
|
+
### 4. Dispatch the remaining batches in waves
|
|
87
|
+
|
|
88
|
+
Send up to four `{tool:Task}` calls with `subagent_type: prose-reviser` in one message. A harness that returns each before the next is the series case; do not attempt to detect which one you are on.
|
|
89
|
+
|
|
90
|
+
Before each dispatch, write two files under `{scratch}/revise-prose/`: that batch's candidate objects, exactly as the helper reported them and `stale` flags included, to `batch-{index}.json`, and the run's `rejections` entries whose `file` the batch covers, to `rejections-{index}.json`. Write the second even if it does not contain any entry, so that every dispatch names the same keys. `{scratch}` is a scratch directory created once for the run with `mktemp -d "${TMPDIR:-/tmp}/revise-prose.XXXXXX"`, written out as an absolute path in each place below and in each dispatch block, since these writes and the subagent's reads all go through a file tool that does not expand shell syntax.
|
|
91
|
+
|
|
92
|
+
A batch's `rules` value lists its `unswept` rules and step 1's unrecorded rules, sorted, each named once. A rule without a sweep version is therefore swept in every batch that the helper reports, and it never causes a batch to be dispatched. Dispatch each batch with this block:
|
|
93
|
+
|
|
94
|
+
```dispatch
|
|
95
|
+
root: {root}
|
|
96
|
+
files: {the batch's files, comma-separated}
|
|
97
|
+
candidates: {scratch}/revise-prose/batch-{index}.json
|
|
98
|
+
rejections: {scratch}/revise-prose/rejections-{index}.json
|
|
99
|
+
rules: {rule-id}, {rule-id}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**The block contains scalars only, and only these keys.** Do not compose prose into it: The subagent has the rule set and reads the files itself, and a sentence written here would bias its judgment toward yours. A content test fails the build on a line that is not a `key: value` scalar and on a key outside this set.
|
|
103
|
+
|
|
104
|
+
**On each return, parse the report.** It is one fenced JSON block containing `applied`, `rejected`, and `questionable`. If the returned value does not contain such a block, or the block is truncated, redispatch the batch rather than editing from it.
|
|
105
|
+
|
|
106
|
+
**Once the whole wave has returned:**
|
|
107
|
+
|
|
108
|
+
1. **Check the diff against the wave.** Run `git diff --name-only`. Every subagent in the wave has already made its edits by now; therefore, the gate checks against the union of the batches' file lists rather than any one batch's. If the diff names a file outside that union, stop the run and report which file changed; commit nothing.
|
|
109
|
+
2. **Check each report against its own batch.** If a batch's `applied` entries name a file outside that batch's `files` list, stop the run and report which batch named it; commit nothing. The union check above cannot detect this, because that file is in another batch of the same wave.
|
|
110
|
+
3. **Commit each batch in index order.** Stage that batch's files alone and commit them per `{skill:create-commit}`, with the type and the scope that `create-commit` derives from those files.
|
|
111
|
+
4. **Accumulate** the wave's `rejected` and `questionable` entries for step 5.
|
|
112
|
+
|
|
113
|
+
### 5. Close the run
|
|
114
|
+
|
|
115
|
+
1. **Adjudicate the questionables.** Decide each entry yourself before asking the user about any of them. Read the context that decides it: the code around the site; the tests and docs that quote the phrase, found by searching the repository for it with {tool:Grep}; other batches' `applied` entries that repair the same wording; and the docs that the site links to. Then accept or reject the repair, and record the reason. Pass a site to the user only if deciding it requires information that the repository does not contain, or if the repair is in the gated class, such as a change to printed output that a consumer outside the repository may parse. Once every other entry is decided, present the passed sites together in the residue table per [Summary format](#summary-format), each with your recommendation and its reason.
|
|
116
|
+
2. **Apply the accepted repairs**, yours and the user's, with the {tool:Edit} tool, phrase to phrase from each entry's `phrase` and `repair`. If a test expectation or a doc quotes the repaired text, update each quoting file to the repaired text as part of the same repair. Stop at the first edit that does not match, so that the user sees what diverged.
|
|
117
|
+
3. **Compose the fold** and pipe it to the helper's `record` command, which is the record's only write path:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
cat <<'EOF' | node {harness_home_dir}/skills/revise-prose/revise-prose.mjs record
|
|
121
|
+
{"sweptAt":"{today}","roots":["{root}"],"units":{"{name}":"{version}"},"rules":{"{rule-id}":{"unit":"{name}","version":"{rule-version}"}},"rejections":[]}
|
|
122
|
+
EOF
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`sweptAt` is today's ISO calendar date. `roots` lists the invocation's narrowing paths, or `["."]` for a whole-repository sweep. `units` names every unit from step 1 at its current version. `rules` names every rule that step 2 passed with a version, `plain-speech` included, with its unit and its sweep version; the helper records for each whether it has a detector for the rule.
|
|
126
|
+
|
|
127
|
+
`rejections` contains every subagent rejection plus every questionable rejected in step 5.1, by you or by the user, each containing `rule`, `file`, `phrase` as the text reads after this run's edits, and `ground`. A rejected questionable's `ground` is the reason recorded for its rejection. Leave out a rejection under a rule that `rules` does not name, which is a rule without a sweep version: Nothing records such a rule, and the helper refuses the fold.
|
|
128
|
+
|
|
129
|
+
**Fold every rejection under a rule that `rules` names, whether or not the helper has its detector.** Because a rejection resolves to a site by its rule, its file, and its phrase, a rejection under a rule for which the helper does not have a detector is recorded and re-suppressed like any other. Report the phrase as it reads in the source and long enough to locate the site by eye: The helper masks inline code spans and matches by containment, and therefore a span wider than the one reported by the detector still resolves to it. On the next sweep, step 4 writes the recorded sites to the rejections file of each batch that covers them.
|
|
130
|
+
|
|
131
|
+
4. **Commit the closing repairs, the quoting files that they updated, and the record together**, per `{skill:create-commit}`.
|
|
132
|
+
5. **Run the project's quality gate** as `{skill:development-workflows}` resolves it. A test that asserts on a string repaired by a subagent fails there; repair the test expectation and commit that separately.
|
|
133
|
+
6. **Emit the summary** per [Summary format](#summary-format).
|
|
134
|
+
|
|
135
|
+
<!-- include: ../../_partials/plain-speech.md / -->
|
|
136
|
+
|
|
137
|
+
<!-- include: ../../_partials/plain-speech-calibration.md / -->
|
|
138
|
+
|
|
139
|
+
<!-- include: ../../_partials/target-file-set-resolution.md / -->
|
|
140
|
+
|
|
141
|
+
## Summary format
|
|
142
|
+
|
|
143
|
+
One table per batch, then the closing lines:
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
revise-prose summary
|
|
147
|
+
|
|
148
|
+
| Batch | Files | Applied | Rejected | Questionable |
|
|
149
|
+
| ----- | ----- | ------- | -------- | ------------ |
|
|
150
|
+
| 0 | 12 | 31 | 4 | 2 |
|
|
151
|
+
| 1 | 9 | 18 | 1 | 0 |
|
|
152
|
+
|
|
153
|
+
Recorded in `.agents/revise-prose.yaml`: capitalization-after-colon 1, em-dash 1, negative-quantifier 2, plain-speech 9, sentence-case 2.
|
|
154
|
+
Not recorded: other-writing-guidance, prefer-active-voice.
|
|
155
|
+
No detector: capitalization-after-colon, plain-speech, sentence-case.
|
|
156
|
+
5 files excluded: 1 generated, 1 machine-generated, 3 ineligible.
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
The recorded line names each rule from the fold's `rules` at its sweep version. Give the line naming what was not recorded only if step 1 kept an unrecorded rule, naming each kept rule without a sweep version and the slug of each block that is not a unit and from which step 1 kept a rule.
|
|
160
|
+
|
|
161
|
+
Give the excluded-files clause only if `filesSkipped` reports a non-zero count, naming each reason and its count, so that a file that the sweep never opened is not mistaken for a clean result. A whole-repository sweep reports a large `ineligible` count, because every image, lockfile, and data file in the repository is one; a narrowed sweep reports the files that it was given and could not read.
|
|
162
|
+
|
|
163
|
+
Give the line naming the rules without a detector only if the helper's `rules.undetected` lists any, naming each. If a marker misspells a detector rule's id, the misspelled id appears only on this line: The subagent still sweeps the rule wherever a batch applies it, and the helper does not run a detector for it.
|
|
164
|
+
|
|
165
|
+
Present every questionable in the adjudicated table, grouped by ground, before the per-batch tables. A site passed to the user has the verdict that the user's answer gave it.
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
| # | Ground | File | Line | Phrase | Repair | Verdict | Reason |
|
|
169
|
+
| - | ----------------- | ------------- | ---- | ------------------------------- | ----------------------------- | ------- | ---------------------------------------------------- |
|
|
170
|
+
| 1 | plausible exhibit | docs/rules.md | 61 | the source it names | the source that it names | reject | the list above it introduces each line as an exhibit |
|
|
171
|
+
| 2 | changes meaning | src/parse.ts | 22 | the findings arrive as warnings | the function reports warnings | apply | `parse` emits the warnings, per its tests |
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Step 5.1 presents the sites passed to the user in the residue table, which has the same columns with a recommendation, `apply` or `reject`, in place of the verdict:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
| # | Ground | File | Line | Phrase | Repair | Recommendation | Reason |
|
|
178
|
+
| - | ------------- | ---------- | ---- | -------------------- | ----------------------------- | -------------- | ---------------------------------------------- |
|
|
179
|
+
| 1 | asserted text | src/cli.ts | 40 | no config file found | the config file isn't present | reject | release notes document the message for scripts |
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Ask for the numbers of the rows to decide against their recommendation; every unnamed row takes its recommendation.
|
|
183
|
+
|
|
184
|
+
Because there is nothing yet to adjudicate under `--dry-run`, the run reports the candidates instead: one table per file, ordered as the helper reported them, with the rule, the line, and the phrase. If the total is large, the user reads `byFile` and `byShape` to narrow the next run.
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
| Rule | Line | Phrase |
|
|
188
|
+
| ----------------------- | ---- | ----------------------------------- |
|
|
189
|
+
| reduced-object-relative | 14 | the ticket the branch name encodes |
|
|
190
|
+
| em-dash | 22 | Findings arrive as warnings -- ... |
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
194
|
+
|
|
195
|
+
<!-- guidance-hook: comment-preferences -->
|
|
196
|
+
|
|
197
|
+
<!-- guidance-hook: writing-preferences -->
|