Speckit Docs Tidy

.claude/commands/capture-learnings.md

@@ -41,15 +41,9 @@ Run this command at the end of a working session, after completing a feature, or
    - Renamed or moved files (R status) — especially CLAUDE.md, docs, or config files
    - Modifications to `CLAUDE.md` or `.specify/memory/constitution.md`
 
-   When `has_branch_context` is false (running on the default branch, or feature branch with no commits yet), skip this step — only Confidence levels reachable in step 5 are `Medium (chat only)`.
+   When `has_branch_context` is false (running on the default branch, or feature branch with no commits yet), skip this step — only Confidence levels reachable in step 4 are `Medium (chat only)`.
 
-4. **Ask discovery questions**: Before synthesising candidates, ask the user:
-
-   > "Before I write up candidates — was there anything surprising, a wrong assumption I made, or something that took longer than expected that didn't show up clearly in our conversation?"
-
-   Wait for a reply. Incorporate any freeform input as additional candidates.
-
-5. **Synthesise candidates**: Produce at most 5 candidates. Fewer is fine — only include signals that are non-obvious, generalisable, and likely to recur. Skip signals that are clearly one-off, feature-specific, or already documented.
+4. **Synthesise candidates**: Produce at most 5 candidates. Fewer is fine — only include signals that are non-obvious, generalisable, and likely to recur. Skip signals that are clearly one-off, feature-specific, or already documented.
 
    For each candidate write:
 
@@ -68,15 +62,15 @@ Run this command at the end of a working session, after completing a feature, or
    - Structural decision → `.claude/memory/project_*.md`, or note a suggested CLAUDE.md edit
    - Confirmed approach → `.claude/memory/feedback_*.md`
 
-6. **Confirm with the user**: After listing the candidates, ask:
+5. **Confirm with the user**: After listing the candidates, ask:
 
    > "Which of these are worth keeping? Reply with the numbers (e.g. `1 3`), or `none`."
 
    Wait for the reply before writing anything.
 
-7. **Check for duplicates**: For each approved candidate, grep `.claude/memory/` for related terms. If a closely related memory already exists, note whether this should *update* the existing file rather than create a new one.
+6. **Check for duplicates**: For each approved candidate, grep `.claude/memory/` for related terms. If a closely related memory already exists, note whether this should *update* the existing file rather than create a new one.
 
-8. **Write approved learnings**: For each approved candidate, write (or update) a memory file in `.claude/memory/` using this format:
+7. **Write approved learnings**: For each approved candidate, write (or update) a memory file in `.claude/memory/` using this format:
 
    ```markdown
    ---
@@ -85,7 +79,7 @@ Run this command at the end of a working session, after completing a feature, or
    type: feedback | project
    ---
 
-   [Draft from step 5]
+   [Draft from step 4]
 
    **Why:** [inferred from the evidence — the conversation moment or constraint that caused it]
    **How to apply:** [when this should influence future behaviour]
@@ -95,4 +89,4 @@ Run this command at the end of a working session, after completing a feature, or
 
    If the candidate's target was a CLAUDE.md edit rather than a memory file, describe the suggested edit and ask the user whether to apply it.
 
-9. **Output result**: List the files written or updated (or edits proposed). If nothing was approved, output: "No learnings captured."
+8. **Output result**: List the files written or updated (or edits proposed). If nothing was approved, output: "No learnings captured."

.claude/commands/raise-pr.md

@@ -1,31 +1,68 @@
 ---
-description: Raise a PR for the current feature branch with auto-detected spec and CIR links.
+description: Raise a PR for the current feature branch — cleans up the spec folder, composes a PR body sized to the change, and requests an @claude review.
 ---
 
-Read `CLAUDE.md` and `docs/conventions/*.md` for project context before proceeding.
+Read `CLAUDE.md` for project context before proceeding.
 
 ## Steps
 
 1. **Get branch name**: Run `git rev-parse --abbrev-ref HEAD`. If the result is `main`, stop immediately and output: "Run /raise-pr from a feature branch, not main."
 
 2. **Check for commits**: Run `git log main..HEAD --oneline`. If the output is empty, stop immediately and output: "No commits found on this branch compared to main — nothing to raise a PR for."
 
-3. **Get all changed files**: Run `git diff main...HEAD --name-only` to list every file changed on this branch.
+3. **Detect spec folder for this branch**: Run whichever spec-kit prerequisites helper is present in the repo:
+   - POSIX: `bash .specify/scripts/bash/check-prerequisites.sh --json --paths-only`
+   - Windows / pwsh: `pwsh .specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly`
 
-4. **Get added files**: Run `git diff main...HEAD --diff-filter=A --name-only` to list only files new to this branch.
+   If neither script exists, or the command exits non-zero (non-feature branch), skip to step 5.
 
-5. **Extract artifacts** from the added files (step 4):
-   - Spec folders: find any matching `specs/*/spec.md` and extract the parent folder (e.g. `specs/004-raise-pr-command`)
-   - CIR files: find any matching `docs/change-intent-records/*.md` and use the full path (e.g. `docs/change-intent-records/006-slug.md`)
+   Otherwise parse `FEATURE_DIR` from the JSON output. If `FEATURE_DIR` does not exist on disk, skip to step 5. Otherwise keep it for step 4.
 
-6. **Infer PR title**: Take the branch name from step 1, strip any leading `NNN-` numeric prefix, replace hyphens with spaces, and apply title case. Examples: `004-raise-pr-command` → `Raise PR Command`; `add-glider-pattern` → `Add Glider Pattern`.
+4. **Confirm and delete spec folder**: Use `AskUserQuestion` to ask:
+   - Question: "Delete the spec folder `<FEATURE_DIR>` and commit the removal? Specs are typically deleted before merge so they don't accumulate on main."
+   - Options: "Delete and commit" / "Skip"
 
-7. **Build PR body**: Read `.github/pull_request_template.md` to get the section structure. Pre-fill as follows:
-   - **Summary**: Write 2–3 sentences covering what changed, why it was needed, and the approach taken — enough context for an independent reviewer without them needing to read the code first. Draw from the changed files (step 3) and commit list (step 2).
-   - **Spec**: Markdown link to detected spec folder(s), or `N/A` if none detected
-   - **Changed Files**: All files from step 3, one per line
-   - **New Artifacts**: For each detected spec folder or CIR file, one markdown link per line (e.g. `- Spec: [specs/004-raise-pr-command](specs/004-raise-pr-command)`). Omit the section entirely if no artifacts were detected.
+   If "Delete and commit":
+   - Run `git rm -r <FEATURE_DIR>`
+   - Run `git commit -m "chore: remove <FEATURE_DIR>"`
 
-8. **Create PR**: Run `gh pr create --title "<inferred title>" --body "<pr body>"` using the values from steps 6 and 7.
+   If "Skip", proceed without changes.
 
-9. **Output result**: Print the PR URL returned by `gh pr create`. If any spec folders or CIR files were detected in step 5, also print a single line: `Detected: <comma-separated list>`. Omit the `Detected:` line entirely if no spec folders or CIR files were found.
+5. **Infer PR title**: Take the branch name from step 1, strip any leading path segment (`feat/`, `fix/`, `chore/`, `docs/`, etc.), strip any leading `NNN-` numeric prefix on the remaining segment, replace hyphens with spaces, and apply title case. Examples: `004-raise-pr-command` → `Raise PR Command`; `chore/speckit-docs-tidy` → `Speckit Docs Tidy`.
+
+6. **Compose PR body**: Write a description sized to the change. **Do not follow a fixed template.** Decide which sections earn their place based on what's actually in this PR.
+
+   **Guiding principle — don't duplicate things a reviewer can get elsewhere.** GitHub already shows:
+   - the list of changed files and their diffs
+   - the commit list and commit messages
+   - line-count statistics, additions/deletions
+   - the author, base/head branches, and CI status
+
+   Don't repeat any of that in the body. Use the body for things a reviewer *can't* easily get from the code or git history.
+
+   **Sections to consider** (include each only if it adds value for this PR):
+
+   - **Why** — motivation or context that isn't already obvious from commit messages. Skip for trivial PRs where the title is self-explanatory.
+   - **What changes** — a short summary of observable changes. For single-theme PRs, 1–3 bullets. For multi-theme PRs, group by theme rather than by file. Describe *what* changed at a behaviour level, not which files were touched.
+   - **Non-obvious things a reviewer should know** — caveats, deliberate trade-offs, hidden invariants, anything in the diff that looks weird but is intentional. Omit if there are none.
+   - **How to verify** — a markdown checklist of concrete actions a reviewer can perform. Derive items from what actually changed. Omit for pure-documentation PRs where there's nothing functional to exercise.
+   - **Related** — links to issues, prior PRs, or specs that give context. Omit if none.
+
+   A tiny PR may collapse to two sections. A sprawling PR may use all five. Match the size of the body to the size of the change.
+
+7. **Push branch**: Run `git push -u origin <branch>`. Ensures the spec-deletion commit (if any) is included in the PR.
+
+8. **Create PR**: Run `gh pr create --title "<inferred title>" --body "<pr body>"` with the title from step 5 and the body from step 6. Capture the PR URL from the output. Use whatever multi-line string quoting your shell needs (bash heredoc, PowerShell here-string, etc.).
+
+9. **Request @claude review**: Run `gh pr comment <PR URL> --body "<review prompt>"` with this body (same shell-quoting rules as step 8):
+
+   ```
+   @claude Review this pull request. Analyse the code changes and provide feedback covering:
+   - Bugs or correctness issues
+   - Security concerns (including any flagged by static analysis)
+   - Adherence to the project conventions in CLAUDE.md
+   - Test coverage — do the tests adequately cover the new behaviour?
+   - Any spec/test-plan mismatches
+   ```
+
+10. **Output result**: Print the PR URL. If step 4 deleted a spec folder, also print `Deleted spec folder: <FEATURE_DIR>`.

.claude/commands/speckit.confirmissue.md

@@ -121,11 +121,25 @@ The new section is structured as:
 
 <!-- speckit:confirmed-decisions -->
 
+### Requirements    <!-- omit this sub-heading entirely if no requirements decisions -->
+
+- **<title>:** <decision>.
+- **<title>:** <decision>.
+
+### Technical    <!-- omit this sub-heading entirely if no technical decisions -->
+
 - **<title>:** <decision>.
 - **<title>:** <decision>.
-- ...
 ```
 
+Routing rules:
+
+- Bullets corresponding to gaps under `### Requirements gaps` in the review comment go under `### Requirements` here.
+- Bullets corresponding to gaps under `### Technical gaps` in the review comment go under `### Technical` here.
+- If one group has no decisions, **omit its sub-heading entirely** — do not emit an empty `### Technical` section.
+- Strip the gap numbers from the review comment (1, 2, 3, …) when emitting confirmed decisions — bullets here are unordered.
+- **Backwards compatibility:** if the review comment has no `### Requirements gaps` / `### Technical gaps` sub-headings (i.e. it was authored before this convention), emit all decisions as a flat bullet list with no sub-headings (the pre-split format).
+
 Preserve everything above the section byte-for-byte. Do not "tidy" the original proposal.
 
 ### 5. Patch the issue body