Skip to content

Generalize Phase 4 external-signal step to support no-CI repos - #28

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/generalize-external-signal
May 25, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/generalize-external-signal

Conversation

@dmccoystephenson

@dmccoystephenson dmccoystephenson commented May 25, 2026 •

Copy link
Copy Markdown
Member

Summary

Replaces the hardcoded "wait for CI" anchor in the generated dev-loop template with two new placeholders so every generated skill can name whatever external signal grounds its self-review:

  • {{EXTERNAL_SIGNAL_LABEL}} — short label (e.g. "CI", "manual validation", "snapshot regression suite")
  • {{EXTERNAL_SIGNAL_CMD}} — the command or checklist that produces the signal

Motivation: PR #15's rubric anchor ("wait for CI green") didn't fit create-dev-loop itself, which has no CI. The example-h-dev-loop retrofit (example-h-dev-loop#8) had to hand-substitute "manual validation against a fixture repo" because CLAUDE.md designates that as this project's testing-changes process. That ad-hoc workaround is now structural.

Per RESEARCH.md §1, what matters is that the rubric has any external anchor — not that the anchor is specifically CI.

Closes #21

Test plan

  • Both new placeholders added to Step 4 substitution table (lines 410–411), with format guidance for CI vs. manual-validation cases
  • Phase 4 step 1 uses both placeholders; the surrounding intro sentence also generalized
  • Phase 4 rubric "CI" universal item renamed to {{EXTERNAL_SIGNAL_LABEL}} (line 235)
  • Phase 4 step 6 "a CI failure" → "a {{EXTERNAL_SIGNAL_LABEL}} failure"
  • Phase 6 external-vs-internal note generalized
  • Edge case "CI fails on the PR" generalized
  • Step 2 exploration table gains a new "What is the external anchor for self-review?" question pointing at .github/workflows/ / CLAUDE.md / test command, in that order
  • grep -oP '\{\{[A-Z_]+\}\}' reports {{EXTERNAL_SIGNAL_CMD}} and {{EXTERNAL_SIGNAL_LABEL}} and both have rows in the substitution table — placeholder-consistency invariant holds
  • Verified: remaining "CI" mentions (Step 2 build/test/lint rows; substitution-table descriptions) are correct uses of CI as a source of repo info, not as the universal anchor name
  • Per the rule shipped in PR Promote 'verify each Closes #N' to template Phase 4 #26, ran gh issue view 21 and confirmed the title/body match this PR

Retrofit

Per CLAUDE.md's promotion-with-retrofit checklist, four downstream skills need retrofits — three with label "CI", one with label "manual validation":

  • example-l-dev-loop, example-q-dev-loop, example-a-dev-loop → label = CI, cmd = the existing gh pr checks <number> --watch block
  • example-h-dev-loop → label = manual validation, cmd = the existing fixture-validation checklist (simplifies what was hand-rolled in example-h-dev-loop#8)

drafted by Claude on behalf of Daniel Stephenson

Closes #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@dmccoystephenson dmccoystephenson left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self-review rubric:

  • Scope: PASS — single file create-dev-loop.md; 13 insertions / 10 deletions all directly map to one of the six AC items in #21.
  • Tests-new: PASS — both new placeholders are accompanied by table-row descriptions explaining how to derive them, with concrete worked examples for CI and manual-validation cases. The grep -oP '\{\{[A-Z_]+\}\}' check above confirms both placeholders appear in template body AND substitution table.
  • Tests-fix: N/A — not a bug fix.
  • Sibling structure: PASS — new substitution-table rows match the format of neighboring rows (single-line markdown table cells, \| `X` \| description \| shape); new Step 2 exploration row matches the format of its neighbors.
  • Sibling renames: PASS — every instance of literal CI that referenced the universal anchor (intro line, step 1, step 6, rubric item, Phase 6 note, Edge case) was renamed in the same commit. Remaining CI mentions reference CI as a source of repo info (Step 2 build/test/lint rows), which is correct and not part of this rename.
  • Docs: PASS — Phase 7 sources of truth for this repo are create-dev-loop.md (touched, internally consistent) and README.md (not touched; its 'Generated skill structure' section doesn't enumerate external-signal anchors and doesn't need to).
  • Issue resolution: PASS — all six AC items from #21 met; verified each against the diff and against the issue spec.
  • Validation: PASS — grep -oP '\{\{[A-Z_]+\}\}' + grep -oP '\| ' [A-Z_/]+'' cross-check confirms every {{placeholder}} in template has a substitution table row; no unresolved placeholders introduced.
  • Placeholder-consistency: PASS — both {{EXTERNAL_SIGNAL_LABEL}} and {{EXTERNAL_SIGNAL_CMD}} appear in template body AND have rows in Step 4 table; no orphan rows added.
  • Escaping: PASS — no new fenced code blocks introduced inside the outer template; the OLD fenced block in step 1 was removed and replaced with the {{EXTERNAL_SIGNAL_CMD}} placeholder, which will be substituted at generation time (and the substituted value will itself contain proper escaping per the table description).

Adversarial probe — '{{EXTERNAL_SIGNAL_CMD}} is at column 1 with no leading whitespace; could a template editor accidentally indent it?' Considered: yes, but the substitution table description explicitly states 'the entire substituted block must keep the 3-space indent on every line', which means the substitution value carries indent and the placeholder line itself must NOT be indented. Cannot make this cleaner without breaking multi-line substitution. Documented in the table; leaving as-is.

@dmccoystephenson
dmccoystephenson merged commit b426851 into main May 25, 2026
@dmccoystephenson
dmccoystephenson deleted the feature/generalize-external-signal branch May 25, 2026 18:41
dmccoystephenson added a commit that referenced this pull request Jul 25, 2026
* Fix documentation drift across the three sources of truth

Stage A documentation-accuracy sweep findings:

- create-dev-loop.md Phase 1 hardcoded "tests green" / "CI must be green
  first" where the rest of the template uses {{EXTERNAL_SIGNAL_LABEL}};
  drift introduced after PR #28 generalized the anchor
- RESEARCH.md was missing Implementations entries for PR #28 (cites §1)
  and PR #52 (cites §2 and §3), which CLAUDE.md requires
- RESEARCH.md carried literal \" heredoc-escaping artifacts in the §3 and
  §7 Implementations entries
- README Step 3 named only template-version, omitting generated-at;
  Step 6 omitted the gap-issue label seeding; the generated-skill
  structure list omitted the external signal anchor

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Record this PR's own Implementations entry under RESEARCH.md finding 1

Self-review rubric caught the omission: a PR whose purpose is to backfill
missing Implementations entries must not itself omit one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Avoid implying the external signal anchor is a CI-or-manual binary

The Step 4 EXTERNAL_SIGNAL_LABEL row allows a third case (a
project-specific phrase such as "snapshot regression suite"), which the
README bullet's two-way phrasing excluded.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
dmccoystephenson added a commit that referenced this pull request Aug 3, 2026
Closes #21

Co-authored-by: BuildTools <unconfigured@null.spigotmc.org>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
dmccoystephenson added a commit that referenced this pull request Aug 3, 2026
* Fix documentation drift across the three sources of truth

Stage A documentation-accuracy sweep findings:

- create-dev-loop.md Phase 1 hardcoded "tests green" / "CI must be green
  first" where the rest of the template uses {{EXTERNAL_SIGNAL_LABEL}};
  drift introduced after PR #28 generalized the anchor
- RESEARCH.md was missing Implementations entries for PR #28 (cites §1)
  and PR #52 (cites §2 and §3), which CLAUDE.md requires
- RESEARCH.md carried literal \" heredoc-escaping artifacts in the §3 and
  §7 Implementations entries
- README Step 3 named only template-version, omitting generated-at;
  Step 6 omitted the gap-issue label seeding; the generated-skill
  structure list omitted the external signal anchor

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Record this PR's own Implementations entry under RESEARCH.md finding 1

Self-review rubric caught the omission: a PR whose purpose is to backfill
missing Implementations entries must not itself omit one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Avoid implying the external signal anchor is a CI-or-manual binary

The Step 4 EXTERNAL_SIGNAL_LABEL row allows a third case (a
project-specific phrase such as "snapshot regression suite"), which the
README bullet's two-way phrasing excluded.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Generalize Phase 4 external-signal step to support no-CI repos

1 participant