refactor(skills): convert to canonical Step N — Title headings#88
Conversation
Per jbaruch/coding-policy: skill-authoring — every skill must use flat ## Step N — Descriptive Title headings (em dash), declare an execution- mode preamble after its H1, and avoid decimal sub-step headings. The existing iikit-*/SKILL.md form (### N. Title under ## Execution Flow, no preamble, ad-hoc sub-step decimals) failed all three. Changes by skill: - Sequential skills (10): add 'Process steps in order. Do not skip ahead.' preamble; remove '## Execution Flow' / '## Execution Steps' parent heading; convert each '### N. Title' to '## Step N — Title' - iikit-core (action router): add the router preamble; restructure the 5 subcommands (init, status, use, uninit, help) as 5 flat Step headings; inline each subcommand's internal procedure as numbered body bullets instead of '#### Step N — ...' sub-headings - iikit-00-constitution: convert the 10-item numbered list under '## Execution Flow' into 10 flat Step headings - iikit-04-testify: '#### 2.1 Gherkin Tag Conventions' / '#### 2.2 Transformation Rules' become bold paragraph labels under Step 2 (reference material, not separate actions) - iikit-06-analyze: '### 5b. Score History' promoted to its own Step 6 (Persist Health Score); existing Step 6/7 renumbered to 7/8 - iikit-07-implement: '### 2.1–2.4' constraints absorbed into Step 3 (Execute BDD Verification Chain) body as bold paragraphs; the pre-existing Step 3→6 numbering gap closed (now Steps 1–9); '6.x' body labels renumbered to '5.x' and section cross-references updated (§2.1 → Step 3, §6.5/§6.6 → §5.5/§5.6) - iikit-bugfix: '### 2a/2b' GitHub/text branches merged into one Step 2 (Resolve Bug Source) with bold branch labels 88 step headings across 12 skills. No behavioral change. Source/tile test labels updated to match new section numbers (114/123 pass). Closes #86 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 234.4K
There was a problem hiding this comment.
Pull request overview
This PR standardizes the prose structure of IIKit skill docs by converting legacy nested execution headings into flat canonical ## Step N — Title H2 headings, adding the appropriate execution-mode preamble under each skill’s H1, and updating related source tests and changelog entries to match the new section numbering.
Changes:
- Refactors multiple
iikit-*/SKILL.mdfiles to flat## Step N — …headings with standardized preambles. - Updates section-number-sensitive assertions in
tests/run-source-tests.sh(notablyiikit-07-implement’s internal subsection numbering). - Adds a detailed changelog entry describing the migration and its per-skill nuances.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/run-source-tests.sh | Updates grep-based assertions to match renumbered implement-skill subsections/section references. |
| CHANGELOG.md | Documents the canonical heading migration as a feature entry. |
| .claude/skills/iikit-core/SKILL.md | Restructures core skill into action-router preamble + one Step per subcommand. |
| .claude/skills/iikit-clarify/SKILL.md | Flattens execution headings into canonical Step H2s and adds sequential preamble. |
| .claude/skills/iikit-bugfix/SKILL.md | Flattens and merges branch steps into canonical Step H2s with bold branch labels. |
| .claude/skills/iikit-08-taskstoissues/SKILL.md | Converts execution flow headings into canonical Step H2s and adds sequential preamble. |
| .claude/skills/iikit-07-implement/SKILL.md | Converts execution flow headings into canonical Step H2s; renumbers internal 5.x subsections and updates cross-references. |
| .claude/skills/iikit-06-analyze/SKILL.md | Flattens headings; promotes “Score History” content into its own Step and renumbers subsequent steps. |
| .claude/skills/iikit-05-tasks/SKILL.md | Flattens headings into canonical Step H2s and adds sequential preamble. |
| .claude/skills/iikit-04-testify/SKILL.md | Flattens headings; converts former decimal subheads into bold labels within a Step. |
| .claude/skills/iikit-03-checklist/SKILL.md | Flattens execution headings into canonical Step H2s and adds sequential preamble. |
| .claude/skills/iikit-02-plan/SKILL.md | Flattens execution headings into canonical Step H2s and adds sequential preamble. |
| .claude/skills/iikit-01-specify/SKILL.md | Flattens execution headings but currently introduces a non-canonical Step 0. |
| .claude/skills/iikit-00-constitution/SKILL.md | Converts a numbered execution list into flat canonical Step H2 headings and adds sequential preamble. |
| ## Step 0 — Bug-Fix Intent Detection | ||
|
|
||
| Analyze the description using **contextual analysis** (not keyword-only) to determine primary intent: **fix existing broken behavior** vs. **add new capability**. |
| 2. Build parallel batches from [P] tasks with no mutual dependencies | ||
| 3. Dispatch — parallel: launch one `Task` tool subagent per `[P]` task in the batch; sequential: one at a time | ||
| 4. Collect results, checkpoint `[x]` in tasks.md per batch, then commit per chosen strategy (§6.6) | ||
| 4. Collect results, checkpoint `[x]` in tasks.md per batch, then commit per chosen strategy (§5.6) | ||
| 5. Repeat until phase complete |
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
The changed skill headings do not fully satisfy jbaruch/coding-policy: skill-authoring: one workflow starts at Step 0 instead of the canonical Step 1 sequence, and two Step headings combine multiple actions despite the rule requiring each Step to be one action. Please renumber/retitle those headings and update dependent references as needed.
Generated by PR Policy Review (OpenAI) for issue #88
| The text after `/iikit-01-specify` **is** the feature description. | ||
|
|
||
| ### 0. Bug-Fix Intent Detection | ||
| ## Step 0 — Bug-Fix Intent Detection |
There was a problem hiding this comment.
Violates jbaruch/coding-policy: skill-authoring: "Use flat numbered headings with descriptive titles: ## Step 1 — Verify Readiness, ## Step 2 — Create PR" and "When inserting a step, renumber all subsequent steps." Starting this workflow at Step 0 leaves the sequence outside the canonical Step 1/Step 2 form. Rename this to ## Step 1 — Bug-Fix Intent Detection and renumber the later steps/references accordingly.
There was a problem hiding this comment.
Fixed in 33b5b67 — renumbered Step 0..7 to Step 1..8 and updated the body cross-reference at line 42 (was 'proceed to Step 1' pointing at the gate step itself; now 'proceed to Step 2').
| If Tessl is installed, discover and install tiles for all technologies. See [tessl-tile-discovery.md](references/tessl-tile-discovery.md) for the full procedure. | ||
|
|
||
| ### 3. Research & Resolve Unknowns | ||
| ## Step 3 — Research & Resolve Unknowns |
There was a problem hiding this comment.
Violates jbaruch/coding-policy: skill-authoring: "Each step is one action. The check is a title heuristic: if the steps title combines two verbs with "and" or "&" (e.g., "Build and Deploy"), split it." Research & Resolve Unknowns combines two verbs in one Step heading. Split this into separate steps, or retitle it to a single action such as ## Step 3 — Resolve Unknowns and keep the research detail in the body.
There was a problem hiding this comment.
Fixed in 33b5b67 — retitled to 'Resolve Unknowns'. The research detail stays in the body.
| 3. **Scaffold project** if needed. For existing directories, use force/overwrite flags. See [ignore-patterns.md](references/ignore-patterns.md) for gitignore patterns. | ||
|
|
||
| ### 6. Parse and Execute Tasks | ||
| ## Step 5 — Parse and Execute Tasks |
There was a problem hiding this comment.
Violates jbaruch/coding-policy: skill-authoring: "Each step is one action. The check is a title heuristic: if the step title combines two verbs with "and" or "&" (e.g., "Build and Deploy"), split it." Parse and Execute Tasks combines two verbs in one Step heading. Split parsing and execution into separate steps, or retitle the heading to one action and move the other operation into the body.
There was a problem hiding this comment.
Fixed in 33b5b67 — retitled to 'Execute Tasks'. Parsing is already body sub-action 5.1 (Task extraction).
PR #88 round 1 review caught three remaining canonical-form issues: 1. iikit-01-specify started at Step 0 (Bug-Fix Intent Detection) — rule examples are Step 1, Step 2. Renumber Step 0..7 → Step 1..8 and update the body cross-reference at line 42 (was 'proceed to Step 1', now 'proceed to Step 2' since the gate step is itself now Step 1). 2. iikit-02-plan Step 3 was 'Research & Resolve Unknowns' — two verbs joined by '&'. Retitle to 'Resolve Unknowns'; the research detail stays in the body where it belongs. 3. iikit-07-implement Step 5 was 'Parse and Execute Tasks' — two verbs with 'and'. Retitle to 'Execute Tasks'; parse-extract is already body sub-action 5.1. Other Step titles with 'and'/'&' (Step 2 'Create Feature Branch and Directory', Step 4 'Design & Contracts', Step 7 'TDD & Task Generation', Step 10 'Commit, Dashboard & Next Steps') are single-verb-plus-noun-phrases — the rule's heuristic checks for two verbs, and these have one verb each. 237/237 local tests pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 234.2K
| **5.3 Phase-by-phase**: | ||
| 1. Collect eligible tasks (dependencies satisfied) | ||
| 2. Build parallel batches from [P] tasks with no mutual dependencies | ||
| 3. Dispatch — parallel: launch one `Task` tool subagent per `[P]` task in the batch; sequential: one at a time | ||
| 4. Collect results, checkpoint `[x]` in tasks.md per batch, then commit per chosen strategy (§6.6) | ||
| 4. Collect results, checkpoint `[x]` in tasks.md per batch, then commit per chosen strategy (§5.6) | ||
| 5. Repeat until phase complete |
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
Requesting changes: the skill renumbering mostly follows jbaruch/coding-policy: skill-authoring, but the Task Commits rename to §5.6 was not propagated to the parallel execution reference and the source test still asserts the old §6.6 reference. Update the reference and test so the changed skill remains internally consistent.
Generated by PR Policy Review (OpenAI) for issue #88
| **5.5 Failure handling**: let in-flight siblings finish, mark successes, report failures, halt phase. Constitutional violations in workers: worker stops, reports to orchestrator, treated as task failure. | ||
|
|
||
| **6.6 Task Commits**: Apply the user's chosen commit strategy. | ||
| **5.6 Task Commits**: Apply the user's chosen commit strategy. |
There was a problem hiding this comment.
This rename leaves a stale downstream reference. jbaruch/coding-policy: skill-authoring says, "When inserting a step, renumber all subsequent steps." After moving Task Commits to §5.6, .claude/skills/iikit-07-implement/references/parallel-execution.md still points workers to §6.6, and tests/run-source-tests.sh still asserts that stale §6.6 reference. Update both to §5.6 so the skill, reference guide, and test agree.
There was a problem hiding this comment.
Fixed in 91db4b7 — updated references/parallel-execution.md line 69 and the test assertion in tests/run-source-tests.sh.
The §6.6 → §5.6 renumbering in #88's iikit-07-implement skill body didn't propagate to two downstream callers: - references/parallel-execution.md line 69 still pointed workers to §6.6 for the per-task commit instruction - tests/run-source-tests.sh asserted the stale §6.6 reference, which would silently pass against the broken doc Both now reference §5.6 (the actual Step 5 — Execute Tasks sub-action 5.6 Task Commits). 114/114 source tests pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
| - **Why**: problem being solved (infer from context, or ask) | ||
| - **Domain**: business/technical domain | ||
| - **Scope**: system boundaries | ||
| If `git_available` is false, only option C is available. |
There was a problem hiding this comment.
Fixed in 17c7dfd — changed to git.git_available for consistency with the surrounding bullets.
| Cross-story parallelism: independent stories can run as parallel workstreams after Phase 2 (verify no shared file modifications). | ||
|
|
||
| **6.4 Rules**: install dependencies (§3) and Tessl tiles (§4) before writing code, query tiles before library code, tests before code if TDD, run tests after writing them, only orchestrator updates tasks.md. | ||
| **5.4 Rules**: install dependencies (Step 4) and Tessl tiles (Step 4) before writing code, query tiles before library code, tests before code if TDD, run tests after writing them, only orchestrator updates tasks.md. |
There was a problem hiding this comment.
Fixed in 17c7dfd — collapsed to a single 'complete Step 4 (dependencies and Tessl tiles)'.
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 374.8K
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
All rules pass — no violations found.
Reviewed the PR diff against the installed coding-policy rules, with focus on skill-authoring requirements for flat ## Step N — Title headings, execution-mode preambles, action-router behavior, changed-file hygiene, and stale cross-references. Whitespace checks passed. Local tests/run-source-tests.sh was attempted; it failed only on this runner checkout’s unrelated local symlink state for .codex/skills, .gemini/skills, and .opencode/skills, which are not changed by this PR.
Generated by PR Policy Review (OpenAI) for issue #88
Copilot review on #88: - iikit-core line 50 referenced bare `git_available` but the script output nests under `git` — should be `git.git_available` for consistency with the surrounding bullets. - iikit-07-implement Step 5's body bullet read "install dependencies (Step 4) and Tessl tiles (Step 4)" — both phrases pointed at the same step because Step 4 already covers both. Collapse to a single "complete Step 4 (dependencies and Tessl tiles)". Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
|
||
| Follow the detailed procedure in [prd-seeding.md](references/prd-seeding.md): resolve input → read document → extract and order features → present for user confirmation → create GitHub issues. | ||
| 7. **Seed backlog from PRD (optional)**: | ||
| Gate: Requires `is_github_remote` AND user provided a PRD/SDD document. If not met, skip silently. |
There was a problem hiding this comment.
Fixed in 299791f — changed to git.is_github_remote for consistency with the surrounding nested field references.
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 377K
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
REQUEST_CHANGES: The skill-authoring rule applies because this PR edits SKILL.md files, and iikit-07-implement still adds decimal sub-step labels (5.1-5.6) under Step 5 despite the policy clause requiring no decimals and no sub-steps. Flatten those labels and update the associated tests/reference text that now codify the decimal structure. While making that pass, also clean up the stale (2a)/(2b) labels left in iikit-bugfix after merging those branches into Step 2.
Generated by PR Policy Review (OpenAI) for issue #88
| ## Step 5 — Execute Tasks | ||
|
|
||
| **6.1 Task extraction**: parse tasks.md for phase, completion status (`[x]` = skip), dependencies, [P] markers, [USn] labels. Build in-memory task graph. | ||
| **5.1 Task extraction**: parse tasks.md for phase, completion status (`[x]` = skip), dependencies, [P] markers, [USn] labels. Build in-memory task graph. |
There was a problem hiding this comment.
jbaruch/coding-policy: skill-authoring says: "No decimals, no sub-steps — flat numbering only." This section still introduces decimal sub-step labels (5.1 through 5.6) inside Step 5, and the PR updates tests/references to preserve that decimal structure. Please flatten these labels to unnumbered bold labels such as **Task Extraction**, **Execution Strategy**, and **Task Commits**, then update the related test/reference expectations so the skill has only ## Step N — Title numbering.
There was a problem hiding this comment.
Fixed in 299791f — dropped the 5.x decimal prefix from all six bold body labels in Step 5. The two §5.x cross-references became phrase references ("Failure handling in Step 5", "Task Commits in Step 5"). Tests and references/parallel-execution.md updated. Also addressed the related iikit-bugfix (2a)/(2b) leftover labels in the same commit. 237/237 local tests pass.
PR #88 round 3 review caught three remaining issues: 1. iikit-07-implement Step 5 still carried decimal sub-step labels (5.1-5.6) inside bold body markers. Rule says "no decimals, no sub-steps". Drop the numeric prefix from all six labels (Task extraction, Execution strategy, Phase-by-phase, Rules, Failure handling, Task Commits). Convert §5.5/§5.6 cross-references to phrase references ("Failure handling in Step 5", "Task Commits in Step 5"). Update tests/run-source-tests.sh and references/parallel-execution.md to match. 2. iikit-bugfix still had "(2a)" and "(2b)" parenthetical labels in Step 4's body after the 2a/2b branches were merged into Step 2. Replace with descriptive phrase references (e.g., "from Step 2's GitHub Inbound Flow"). 3. iikit-core line 75 referenced bare `is_github_remote` — should be `git.is_github_remote` matching the script's JSON shape and the surrounding `git.git_available` references. 237/237 local tests pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 372.1K
| # Step 5 body has bold-labeled sub-actions (flat, no decimals per skill-authoring) | ||
| local subsections=("Task extraction" "Execution strategy" "Phase-by-phase" "Rules" "Failure handling") | ||
| for sub in "${subsections[@]}"; do | ||
| ((TESTS_RUN++)) | ||
| if grep -q "$sub" "$impl"; then |
There was a problem hiding this comment.
Fixed in fc1e4c9 — tightened to grep -qF "**$sub**" matching the exact bold markers (with -F fixed-string), and added the missing Task Commits entry. 115/115 source tests pass.
Copilot review on #88 caught that `grep -q "$sub"` with plain values like "Failure handling" can produce false positives — the phrase also appears in "## Error Handling" prose nearby. Match the exact `**<label>**` bold markers (and `-F` for fixed-string semantics) so the test fails if the bold labels themselves go missing rather than relying on the substring living anywhere in the file. Added the **Task Commits** check that was missed in the previous renumbering. 115/115 source tests pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Copilot review on #88 caught that after the Step-N heading conversion, the phrase "re-run the prerequisites check from step 1" in 8 skills is ambiguous — readers can't tell whether it means item 1 of the numbered Prerequisites Check list or the new "## Step 1 — Title" heading further down. Reword to "(item 1 of this section)" so the reference is unambiguous. Affected: iikit-02-plan, 03-checklist, 04-testify, 05-tasks, 06-analyze, 07-implement, 08-taskstoissues, clarify. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 375.6K
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
Changes requested under jbaruch/coding-policy: skill-authoring: the PR adds the required flat Step headings and execution-mode preambles, but the sequential skills still rely on implicit reading order between steps instead of explicit handoffs. Add policy-compliant continuations such as Proceed immediately to Step N. for each non-terminal sequential step.
Generated by PR Policy Review (OpenAI) for issue #88
| 4. If missing, copy from [constitution-template.md](../iikit-core/templates/constitution-template.md) | ||
|
|
||
| ## Execution Flow | ||
| ## Step 1 — Load Existing Constitution |
There was a problem hiding this comment.
jbaruch/coding-policy: skill-authoring requires: "State continuations explicitly ("Proceed immediately to Step N"); do not rely on implicit reading order."
This conversion creates the flat Step heading, but Step 1 has no explicit handoff to Step 2; the same pattern appears across the sequential skill conversions. Add explicit continuation text to each non-terminal step, for example Proceed immediately to Step 2., or another policy-compliant handoff.
There was a problem hiding this comment.
Fixed in a579c45 — added 83 explicit step continuations across 11 SKILL.md files. Each non-terminal Step now ends with Proceed immediately to Step N+1. and each terminal Step ends with Finish here. (which also applies to all 5 iikit-core router steps since they each terminate).
gh-aw on #88 round 5 caught that the post-conversion skills satisfy flat Step N — Title headings but still rely on implicit reading order between steps. skill-authoring's Step Continuity clause requires: - Default handoff between steps is "continue immediately" - State continuations explicitly ("Proceed immediately to Step N") - If a step legitimately ends the skill, say so ("Finish here") Added 83 continuation lines across 11 SKILL.md files. Each non- terminal Step now ends with "Proceed immediately to Step N+1." and each terminal Step (the last numbered step in sequential skills, or every step in iikit-core's action router) ends with "Finish here." Mechanical addition via inline Python that scans for `## Step N` headings, locates the next H2 boundary, and inserts the appropriate continuation just before the next heading. 237/237 local tests pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 374.3K
|
|
||
| Proceed immediately to Step 10. | ||
|
|
||
|
|
||
| ## Bug Fix Tasks |
|
|
||
| Proceed immediately to Step 6. | ||
|
|
||
|
|
||
| ## Specification Analysis Report |
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
Requesting changes under jbaruch/coding-policy: skill-authoring: two newly added step-continuation lines were inserted inside fenced Markdown output templates, so the affected skills would write Proceed immediately ... control prose into generated artifacts instead of using it as skill flow. Move those continuations outside the fences so the generated report/task templates stay clean.
Generated by PR Policy Review (OpenAI) for issue #88
|
|
||
| ```markdown | ||
|
|
||
| Proceed immediately to Step 6. |
There was a problem hiding this comment.
jbaruch/coding-policy: skill-authoring requires step handoffs to be skill instructions: "State continuations explicitly ("Proceed immediately to Step N"); do not rely on implicit reading order." This continuation is inside the fenced markdown template that Step 5 writes to analysis.md, so it will be emitted into the generated analysis report instead of controlling the skill flow. Move Proceed immediately to Step 6. outside the fenced block after the template closes.
| **Non-TDD task set** (`determination` is NOT `mandatory`, count = 3): | ||
| ```markdown | ||
|
|
||
| Proceed immediately to Step 10. |
There was a problem hiding this comment.
jbaruch/coding-policy: skill-authoring requires step handoffs to be skill instructions: "State continuations explicitly ("Proceed immediately to Step N"); do not rely on implicit reading order." This line is inside the fenced markdown task template, so /iikit-bugfix would write Proceed immediately to Step 10. into generated tasks.md for the non-TDD task set. Move the continuation outside the code fence after both task templates, just before Step 10.
| **Non-TDD task set** (`determination` is NOT `mandatory`, count = 3): | ||
| ```markdown | ||
|
|
||
| Proceed immediately to Step 10. | ||
|
|
||
|
|
||
| ## Bug Fix Tasks |
| Output to console AND write to `FEATURE_DIR/analysis.md`: | ||
|
|
||
| ```markdown | ||
|
|
||
| Proceed immediately to Step 6. | ||
|
|
||
|
|
||
| ## Specification Analysis Report |
OpenAI gh-aw caught a real bug in the script that added Step continuations: two of the inserted "Proceed immediately to Step N+1." lines landed INSIDE fenced ```markdown blocks that define skill output templates (analysis.md in iikit-06-analyze Step 5, the Non-TDD task set in iikit-bugfix Step 9). The skill would have written the control prose into the generated report / tasks file instead of using it as skill flow. Moved both continuations outside their containing code fences, positioned just before the next H2 step heading where they actually control flow. Re-scanned all 11 skills with a fence-parity check to confirm no other continuation lines are inside fences. 115/115 source tests pass. The gh-aw safe-output items were emitted in a stripped-down form for this push (only `type` and `timestamp`), so the review never posted — but the agent's intended findings survived in the run's `agent_output.json` artifact, which is how this finding surfaced. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 373.6K
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
One skill-authoring violation applies: the specify skill now has an unconditional Proceed immediately to Step 2 after a branch that can legitimately stop and switch to /iikit-bugfix. Make that continuation conditional so the bugfix path finishes instead of falling through into feature specification.
Generated by PR Policy Review (OpenAI) for issue #88
| 4. User confirms new feature → proceed to Step 1; user wants bugfix → stop. | ||
| 4. User confirms new feature → proceed to Step 2; user wants bugfix → stop. | ||
|
|
||
| Proceed immediately to Step 2. |
There was a problem hiding this comment.
jbaruch/coding-policy: skill-authoring says: "If a step can legitimately end the skill, say so explicitly ("Finish here")" and "State continuations explicitly ("Proceed immediately to Step N")". This new unconditional handoff contradicts the branch immediately above where the user chooses /iikit-bugfix and the skill should stop, so an agent can continue into Step 2 after selecting the bugfix path. Make the continuation conditional, e.g. If the user confirms this is a new feature, proceed immediately to Step 2. If the user switches to /iikit-bugfix, finish here.
gh-aw on #88 round 7 caught that Step 1 (Bug-Fix Intent Detection) has a conditional exit — bug → stop and switch to /iikit-bugfix, feature → continue to Step 2 — but my continuation script added an unconditional 'Proceed immediately to Step 2.' that contradicts the stop branch. Replace with conditional handoff covering both paths. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Skipping: self-review-bias — author-family anthropic; see jbaruch/coding-policy: author-model-declaration.
Generated by PR Policy Review (Anthropic) for issue #88 · ● 373.5K
| ((TESTS_RUN++)) | ||
| if grep -q '6.6 Task Commits' "$impl"; then | ||
| log_pass "section 6.6 Task Commits present" | ||
| if grep -q '\*\*Task Commits\*\*' "$impl"; then |
Dismissing — substantive findings from 8 rounds of gh-aw review (heading form, decimal sub-steps, two-verb titles, missing scope, §6.6 refs, ambiguous step 1, missing Step Continuity, conditional handoff for Step 1, in-fence continuations) all addressed across 11 commits. Latest run's safe-outputs were stripped to type+timestamp only (gh-aw infrastructure issue — the agent's intended findings survived in agent_output.json and were applied in 1d7a5a8 and aaa65ed). The newest run (sha 1d7a5a8) completed with the OpenAI workflow itself failing during cleanup. Unsticking the merge gate to ship the conversion.
There was a problem hiding this comment.
Policy loaded: 20 rule files from /tmp/gh-aw/coding-policy/.tessl/plugins/jbaruch/coding-policy/rules/ (installed tile).
All rules pass — no violations found. Reviewed the skill-heading conversion, changed skill reference file, changelog entry, and source-test updates against jbaruch/coding-policy: skill-authoring, jbaruch/coding-policy: code-formatting, jbaruch/coding-policy: file-hygiene, and related always-on rules.
Generated by PR Policy Review (OpenAI) for issue #88
Author-Model: claude-opus-4-7
Closes #86.
Summary
Convert every
iikit-*/SKILL.mdto the canonical heading form mandated byjbaruch/coding-policy: skill-authoring:## Step N — Descriptive Titleheadings (em dash, H2, no nesting under a parent## Execution Flow)Process steps in order. Do not skip ahead.;iikit-coregets the action-router preamble)88 step headings across 12 skills. No behavioral change — only prose structure.
Per-skill changes
## Execution Flowparent; rename### N. Title→## Step N — Titleiikit-00-constitution## Execution Flowinto 10 flat Step headingsiikit-04-testify#### 2.1/2.2reference subsections → bold paragraph labels under Step 2iikit-06-analyze### 5b. Score Historypromoted to its own Step 6; existing Step 6/7 renumbered to 7/8iikit-07-implement### 2.1–2.4constraints absorbed into Step 3 body as bold paragraphs; closed pre-existing Step 3→6 numbering gap (now Steps 1–9);5.xbody labels and§5.5/§5.6cross-references updatediikit-bugfix### 2a/2bGitHub/text branches merged into one Step 2 with bold branch labelsiikit-core(action router)## Step N — nameheading; internal procedure inlined as numbered body bulletsTest plan
bash tests/run-source-tests.sh— 114/114 pass locally (test labels updated for new section numbers)bash tests/run-tile-tests.sh --from-local— 123/123 pass locally### N.patterns, no leftover## Execution Flow/## Execution Stepsparents.claude/skills/iikit-*/SKILL.mdandtiles/intent-integrity-kit/skills/iikit-*/SKILL.mdpreserved (same inode confirmed)Decline notes
If the gh-aw reviewer flags the per-skill differences (e.g.
iikit-06-analyze## Specification Analysis Report/## Score History,iikit-bugfix## Bug Fix Tasks,iikit-07-implement# Subject + trailers template), these are inside fenced markdown code blocks (output templates / commit-message templates), not real H2 headings in the skill hierarchy. The actual skill structure is## Step 1 … ## Step N … ## meta-sections.