chore: spec-planning-guidance

[satyaborg]

Improve Spec Skill Planning

Problem

The bundled devloop-spec skill already has an interview gate, source resolution, and standard template, but it does not explicitly require agents to inspect repository facts before asking questions, separate repo-discoverable facts from user decisions, recommend an answer for each decision question, or checkpoint the test seam before final drafting. This hurts when a user asks Devloop to turn settled context into a spec: the agent can re-interview unnecessarily, ask broad questions before reading local files, or leave the implementation agent with a diffuse test plan.

Outcome

skills/devloop-spec/SKILL.md gives stronger planning instructions while keeping the existing spec template shape intact. The shell test suite asserts the new guidance strings, and bash scripts/devloop_test.sh passes without any CLI, renderer, README, issue-publishing, ADR, or glossary changes.

Acceptance Criteria

AC1: skills/devloop-spec/SKILL.md contains a "Discovery before interview" rule requiring repo facts, commands, paths, existing tests, and local conventions to be inspected before user questions.
AC2: skills/devloop-spec/SKILL.md contains a "Facts vs decisions" rule saying facts are discovered from the repo and decisions are asked of the user.
AC3: skills/devloop-spec/SKILL.md tells agents to ask user decisions one at a time with a recommended answer.
AC4: skills/devloop-spec/SKILL.md tells agents to walk dependency decisions in order, with parent decisions before downstream details.
AC5: skills/devloop-spec/SKILL.md tells agents to synthesize settled context directly without re-interviewing.
AC6: skills/devloop-spec/SKILL.md limits follow-up questions to answers that would change scope, behavior, acceptance criteria, test seams, or implementation slice.
AC7: skills/devloop-spec/SKILL.md requires a test seam checkpoint before final drafting that identifies the highest stable existing test seam, prefers one seam when practical, and includes the chosen seam in the Test plan.
AC8: skills/devloop-spec/SKILL.md states that during spec discovery and interview, agents must not implement the requested product or code change.
AC9: skills/devloop-spec/references/spec-template.md is unchanged.
AC10: scripts/devloop_test.sh asserts guidance strings covering facts discovered from repo before user questions, user decisions asked one at a time with a recommended answer, settled context synthesized without re-interviewing, highest stable test seam preference, and no implementation during spec discovery.
AC11: bash scripts/devloop_test.sh passes.

Review Trail

Review rounds and the final report are posted as PR comments below.

---

Generated by devloop.sh

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	devloop	8b81dea	Commit Preview URL Branch Preview URL	Jul 10 2026, 04:57 AM

[satyaborg]

Devloop Review Round 1

• Verdict: ACCEPT

Review 1

Verdict: ACCEPT

Acceptance matrix

Criterion	Status	Implementation evidence	Test evidence
AC1	PASS	skills/devloop-spec/SKILL.md:45 "Discovery before interview: Discover repo facts before user questions. Before asking, inspect repository facts, available commands, relevant paths, existing tests, and local conventions whenever a repo is available."	scripts/devloop_test.sh:128 asserts "Discover repo facts before user questions."; suite green
AC2	PASS	SKILL.md:46 "Facts vs decisions: Facts are discovered from the repo; decisions are asked of the user."	devloop_test.sh:129 asserts the "Facts are discovered from the repo; decisions are asked of the user." string; suite green
AC3	PASS	SKILL.md:47 "User decisions: Ask one user decision at a time and include your recommended answer."	devloop_test.sh:130 asserts "Ask one user decision at a time and include your recommended answer."; suite green
AC4	PASS	SKILL.md:48 "Dependency order: Walk dependency decisions in order: parent decisions before downstream details."	devloop_test.sh:131 asserts the dependency-order string; suite green
AC5	PASS	SKILL.md:49 "Settled context: If supplied context is already settled, synthesize it directly without re-interviewing."	devloop_test.sh:132 asserts the settled-context string; suite green
AC6	PASS	SKILL.md:50 "Follow-up threshold: Only ask follow-up questions that would change scope, behavior, acceptance criteria, test seams, or implementation slice."	devloop_test.sh:133 asserts the follow-up-threshold string; suite green
AC7	PASS	SKILL.md:51 "Test seam checkpoint: Before final drafting, identify the highest stable existing test seam; prefer one seam when practical and include the chosen seam in the Test plan. If no stable existing seam covers the change, say that explicitly and choose the smallest appropriate new or updated test seam."	devloop_test.sh:134 asserts the highest-stable-seam sentence; suite green
AC8	PASS	SKILL.md:43 "During spec discovery and interview, do not implement the requested product or code change."	devloop_test.sh:135 asserts that string; suite green
AC9	PASS	git diff --name-status main...HEAD returns only M scripts/devloop_test.sh and M skills/devloop-spec/SKILL.md; references/spec-template.md is absent from the diff	devloop_test.sh:136-137 still assert the unchanged template Mermaid strings; suite green
AC10	PASS	Assertions added in devloop_test.sh:128-135 cover all five required areas: facts before questions (128), one decision + recommended answer (130), settled context without re-interviewing (132), highest stable seam (134), no implementation during discovery (135)	Red evidence in track: assertions added first, failed with "spec skill planning guidance missing: Discover repo facts before user questions."; independently reproduced green (66 ok, 0 not ok)
AC11	PASS	Prompt/guidance + literal-string assertions only	bash scripts/devloop_test.sh run independently: EXIT=0, 66 ok, 0 not ok, incl. ok - 100% project function coverage

Engineering quality matrix

Area	Status	Evidence
Correctness	PASS	Every asserted string matches the SKILL.md text verbatim; the eight new contains assertions use the established substring helper (devloop_test.sh:18-23); full suite green.
Test quality	PASS	Literal-string assertions are the repo's canonical way to verify prompt-only skill guidance (constraint in spec); track records red (assertions failed on pre-change text) then green, satisfying red/green for a guidance change.
Maintainability	PASS	One compact Planning Discipline section (SKILL.md:41-51) placed after the Interview Gate, consistent with surrounding heading/bullet style; no churn elsewhere.
Architecture boundaries	PASS	Diff touches only the two in-scope files; no CLI, renderer, README, template, or installer edits leak in.
Simplicity	PASS	Direct bullet list plus a one-line lead sentence; no new abstraction, flag, or indirection.
Security	N/A	Change is markdown guidance plus shell string assertions; no user input, command execution, filesystem, or dependency surface changes.
Operational safety	N/A	No runtime or behavioral code path changes; nothing to make non-atomic or unrecoverable.

Review flags

• Silent decision: absent - Track records the tradeoffs (single compact section, verbatim guidance strings, other files left unchanged) and residual risk; no undocumented default or risk acceptance.
• Scope drift: absent - git diff main...HEAD is +20 lines across only skills/devloop-spec/SKILL.md and scripts/devloop_test.sh; spec-template, CLI, renderer, README, and installer untouched. Untracked .devloop/ runtime artifacts are correctly left uncommitted.
• Missing test: absent - All five AC10 coverage areas are asserted; the guidance change is verified by the new literal assertions with documented red/green.

Findings

None.

Missing tests

• None.

Fix instructions

None.

Notes

• This is genuinely pass 1: the listed prior review path equals this output path and did not exist before this write, so no resolved findings were carried over.
• Red evidence for the added assertions is taken from the track (not ok - spec skill planning guidance missing: Discover repo facts before user questions.), which is credible given the eight strings did not exist in the pre-change SKILL.md; green was reproduced independently here (EXIT=0, 100% project function coverage).
• The mv: ... backlink-ro-dir/spec.md: Permission denied line in test output is expected: the sync_spec_pr case intentionally exercises a read-only directory and reports ok.

[satyaborg]

Devloop Final Report

Field	Value
Final status	accepted
Pass count	1 / 5
Final verdict	ACCEPT
PR URL	#85
Branch	chore/spec-planning-guidance

Acceptance Matrix Summary

Acceptance matrix

Criterion	Status	Implementation evidence	Test evidence
AC1	PASS	skills/devloop-spec/SKILL.md:45 "Discovery before interview: Discover repo facts before user questions. Before asking, inspect repository facts, available commands, relevant paths, existing tests, and local conventions whenever a repo is available."	scripts/devloop_test.sh:128 asserts "Discover repo facts before user questions."; suite green
AC2	PASS	SKILL.md:46 "Facts vs decisions: Facts are discovered from the repo; decisions are asked of the user."	devloop_test.sh:129 asserts the "Facts are discovered from the repo; decisions are asked of the user." string; suite green
AC3	PASS	SKILL.md:47 "User decisions: Ask one user decision at a time and include your recommended answer."	devloop_test.sh:130 asserts "Ask one user decision at a time and include your recommended answer."; suite green
AC4	PASS	SKILL.md:48 "Dependency order: Walk dependency decisions in order: parent decisions before downstream details."	devloop_test.sh:131 asserts the dependency-order string; suite green
AC5	PASS	SKILL.md:49 "Settled context: If supplied context is already settled, synthesize it directly without re-interviewing."	devloop_test.sh:132 asserts the settled-context string; suite green
AC6	PASS	SKILL.md:50 "Follow-up threshold: Only ask follow-up questions that would change scope, behavior, acceptance criteria, test seams, or implementation slice."	devloop_test.sh:133 asserts the follow-up-threshold string; suite green
AC7	PASS	SKILL.md:51 "Test seam checkpoint: Before final drafting, identify the highest stable existing test seam; prefer one seam when practical and include the chosen seam in the Test plan. If no stable existing seam covers the change, say that explicitly and choose the smallest appropriate new or updated test seam."	devloop_test.sh:134 asserts the highest-stable-seam sentence; suite green
AC8	PASS	SKILL.md:43 "During spec discovery and interview, do not implement the requested product or code change."	devloop_test.sh:135 asserts that string; suite green
AC9	PASS	git diff --name-status main...HEAD returns only M scripts/devloop_test.sh and M skills/devloop-spec/SKILL.md; references/spec-template.md is absent from the diff	devloop_test.sh:136-137 still assert the unchanged template Mermaid strings; suite green
AC10	PASS	Assertions added in devloop_test.sh:128-135 cover all five required areas: facts before questions (128), one decision + recommended answer (130), settled context without re-interviewing (132), highest stable seam (134), no implementation during discovery (135)	Red evidence in track: assertions added first, failed with "spec skill planning guidance missing: Discover repo facts before user questions."; independently reproduced green (66 ok, 0 not ok)
AC11	PASS	Prompt/guidance + literal-string assertions only	bash scripts/devloop_test.sh run independently: EXIT=0, 66 ok, 0 not ok, incl. ok - 100% project function coverage

Engineering Quality Summary

Engineering quality matrix

Area	Status	Evidence
Correctness	PASS	Every asserted string matches the SKILL.md text verbatim; the eight new contains assertions use the established substring helper (devloop_test.sh:18-23); full suite green.
Test quality	PASS	Literal-string assertions are the repo's canonical way to verify prompt-only skill guidance (constraint in spec); track records red (assertions failed on pre-change text) then green, satisfying red/green for a guidance change.
Maintainability	PASS	One compact Planning Discipline section (SKILL.md:41-51) placed after the Interview Gate, consistent with surrounding heading/bullet style; no churn elsewhere.
Architecture boundaries	PASS	Diff touches only the two in-scope files; no CLI, renderer, README, template, or installer edits leak in.
Simplicity	PASS	Direct bullet list plus a one-line lead sentence; no new abstraction, flag, or indirection.
Security	N/A	Change is markdown guidance plus shell string assertions; no user input, command execution, filesystem, or dependency surface changes.
Operational safety	N/A	No runtime or behavioral code path changes; nothing to make non-atomic or unrecoverable.

Implementation Summary

• Final branch: chore/spec-planning-guidance
• Final commit: 8b81dea
• Commit message: chore: spec-planning-guidance

Commit References

• pass 1 8b81dea chore: spec-planning-guidance (scripts/devloop_test.sh, skills/devloop-spec/SKILL.md)

Tests Run

• Verification hook log: not configured
• Review test evidence: see the acceptance matrix summary above.

Residual Risk

• No blocking residual risk was recorded by the final review.