[scodge-24]

Why

The embedding index only ever bootstrapped reactively: an agent had to reach for slice locate, hit the exit-1 no code semantic index hint, and build it — or a human ran it by hand. /slice-codebase only ever rebuilt an existing index (if SEMANTIC*.json exists), never created the first one. So a freshly sliced repo had no index and natural-language discovery silently did nothing.

What

Make the index a setup-time artifact tied to the same trigger that creates the slices:

• SKILL.md Phase 3 — drop the index note buried in the Validate step; add an explicit final "Build the semantic index" step that builds on initial generation (and rebuilds after a re-slice), gated on the semantic feature + OPENROUTER_API_KEY, else tell the user.
• docs/setup.md §2/§6 — note the skill builds the index as its final step; the manual build is the "any time slices change" path.

The reactive exit-1 hint stays as the safety net it already is.

Docs/skill only — no binary changes.

🤖 Generated with Claude Code

[scodge-24]

@greptile review

[greptile-apps]

Greptile Summary

This docs-only PR promotes the semantic index build from a buried validate-step note into an explicit, first-class Phase 3 step 4 in the slice-codebase skill, ensuring slice locate works immediately after a fresh slice rather than only after a user hits the reactive exit-1 hint. It also aligns the Diff Slice Update gate to require both semantic feature and OPENROUTER_API_KEY (not just the feature), and updates docs/setup.md with the corrected §6 cross-reference and updated semantic-index prose.

• SKILL.md: Removes the stale-index note from the validate step; adds step 4 "Build the semantic index" gated on both the semantic binary feature and OPENROUTER_API_KEY, with a clean skip+user-message path when either is absent; aligns the Diff Slice Update step 5 to the same dual gate.
• docs/setup.md: Fixes the §7 → §6 cross-reference in §2, updates the semantic-index prose to note the skill builds it as its final step, and adds a closing paragraph to §6 describing the same behaviour.
• One carry-over from a prior review remains: the ## Output reporting checklist in SKILL.md (lines 190-193) does not include a bullet for the semantic-index built/skipped status, so an agent treating that section as the canonical report template may silently omit it from its final answer.

Confidence Score: 5/5

Docs-only change with no binary modifications; safe to merge.

Both changed files are documentation and skill instructions with no executable code. The cross-reference fix, the new explicit semantic-index step, and the dual-gate alignment in Diff Slice Update are all internally consistent and match the actual CLI behaviour described in docs/setup.md §1.

skills/slice-codebase/SKILL.md — the ## Output section (lines 190-193) still does not include a bullet for semantic-index built/skipped status, which was raised in a prior review and left unresolved by this PR.

Important Files Changed

Filename	Overview
docs/setup.md	Updates §2 cross-reference from §7 to §6 (correct) and expands the semantic-index prose to note the skill builds it automatically; adds a closing paragraph to §6 stating the same. Clean and consistent.
skills/slice-codebase/SKILL.md	Lifts the semantic-index build from a buried validate-step note into an explicit Phase 3 step 4; aligns the Diff Slice Update gate to require both the semantic feature and OPENROUTER_API_KEY. The ## Output reporting checklist (lines 190-193) still does not include a bullet for semantic-index built/skipped status, which was flagged in a prior review and remains unaddressed.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["slice-codebase skill triggered"] --> B{"slices/ present and INDEX.md?"}
    B -- No --> C[Full Slice Generation]
    B -- "exit 0" --> Z[Report: slices up to date]
    B -- "exit 1" --> D[Diff Slice Update]

    C --> C1[Phase 1: Scout agent]
    C1 --> C2[Phase 2: Refine agents in parallel]
    C2 --> C3["slice check --require-verification"]
    C3 -- Pass --> C4["slice sync-index"]
    C3 -- Fail --> C3fix[Fix slice files, re-run]
    C3fix --> C3
    C4 --> C5{"semantic feature + OPENROUTER_API_KEY?"}
    C5 -- Both present --> C6["slice semantic-index --units code"]
    C5 -- Either missing --> C7[Tell user: index not built]
    C6 --> OUT[Output report]
    C7 --> OUT

    D --> D1["git diff since last-updated-sha"]
    D1 --> D2[Scout: identify affected slices]
    D2 --> D3["Update slices + slice sync-index"]
    D3 --> D4["slice check"]
    D4 --> D5{"SEMANTIC*.json exists?"}
    D5 -- No --> OUT
    D5 -- Yes --> D6{"semantic feature + OPENROUTER_API_KEY?"}
    D6 -- Both present --> D7["slice semantic-index --units code"]
    D6 -- Either missing --> D8[Tell user: index stale]
    D7 --> OUT
    D8 --> OUT

Loading

_{Reviews (5): Last reviewed commit: "docs(skill): address review — align diff..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates the documentation around /slice-codebase so the semantic embedding index is treated as a setup-time artifact (when available), making slice locate / slice find --semantic discoverable and usable immediately in freshly-sliced repos.

Changes:

• Moves semantic-index guidance out of the Phase 3 “Validate” step and adds an explicit final “Build the semantic index” step to /slice-codebase’s SKILL.md instructions.
• Updates docs/setup.md to note the skill builds the index as its final step (when semantic + OPENROUTER_API_KEY are present) and clarifies the manual rebuild path when slices change.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
skills/slice-codebase/SKILL.md	Adds an explicit Phase 3 step to build the semantic index so semantic discovery works immediately.
docs/setup.md	Documents the skill’s semantic-index build behavior and the manual (re)build workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

This docs-only PR promotes the semantic index build from a reactive, buried note in the Validate step to an explicit final step (Step 4) in Phase 3 of Full Slice Generation, ensuring slice locate works immediately after a fresh /slice-codebase run instead of silently doing nothing until triggered reactively. docs/setup.md is updated in §2 and §6 to surface the new first-run behaviour.

• SKILL.md: Removes the old conditional "rebuild if SEMANTIC*.json exists" hint from the Validate step and replaces it with an unconditional Step 4 that builds the index on every full generation, gated on the semantic feature and OPENROUTER_API_KEY.
• docs/setup.md: §2 is updated to note the skill builds the index as its final step; §6 gains a closing paragraph summarising the same, giving both the agent runbook and the human setup guide consistent descriptions of the new behaviour.

Confidence Score: 4/5

Documentation-only change with no binary modifications; safe to merge after addressing the two minor inconsistencies flagged.

The core change is well-scoped: the new Step 4 in Full Slice Generation correctly gates on both the binary feature and the API key, and the fallback message is clear. The two issues found are a stale §7 cross-reference in docs/setup.md that now contradicts a new §6 reference just below it, and the Diff Slice Update path (step 5) still lacking the OPENROUTER_API_KEY gate that the parallel Full Generation path now documents — meaning a diff-update with the feature binary but no key set would hit an API error rather than a clean user message.

The Diff Slice Update section in skills/slice-codebase/SKILL.md (step 5) and the §7 cross-reference in docs/setup.md (line 98) both benefit from a small follow-up edit.

Important Files Changed

Filename	Overview
skills/slice-codebase/SKILL.md	Moves semantic index build from a conditional note inside the Validate step to an explicit, unconditional Step 4 in Phase 3; Diff Slice Update (step 5) retains old text but now lacks the API-key gate that the new step 4 documents, creating an inconsistency between the two paths.
docs/setup.md	§2 and §6 updated to describe the skill's new first-run index build; introduces a (see §6) cross-reference while a pre-existing (see §7) reference for the same section still appears earlier in §2, leaving both in the document.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Phase 3 — Validate and Index] --> B[Step 1: slice check --require-verification]
    B --> C{Pass?}
    C -- No --> D[Fix offending slice files, re-run]
    D --> B
    C -- Yes --> E[Step 2: Self-review each card\ndependency direction, section grammar]
    E --> F[Step 3: slice sync-index\ngenerate slices/INDEX.md]
    F --> G{semantic feature\n+ OPENROUTER_API_KEY?}
    G -- Yes --> H[Step 4: slice semantic-index --units code\nbuild embedding index]
    H --> I[slice locate / find --semantic\nwork immediately]
    G -- No --> J[Skip index build\nTell user to run command once available]
    J --> K[Done]
    I --> K

Loading

Comments Outside Diff (2)

1. skills/slice-codebase/SKILL.md, line 158-160 (link)

   The new Full Slice Generation step 4 explicitly gates on both the binary feature and OPENROUTER_API_KEY, and tells the agent to inform the user if either is missing. The parallel Diff Slice Update step 5 only mentions the binary feature gate — if someone has a semantic binary but OPENROUTER_API_KEY unset, the command will run and fail with an API error rather than giving the clean "index wasn't built" message. Aligning the two paths makes both consistent.

   

2. docs/setup.md, line 98-99 (link)

   Conflicting cross-references to the same section: this line says §7 while the new paragraph added just below says §6, and the actual section header is ## 6. Optional: /slice-codebase agent support. Both references point to the same place, so the §7 here is incorrect and now directly contradicts the new §6 text a few lines later.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

_{Reviews (2): Last reviewed commit: "docs(skill): build the semantic index at..." | Re-trigger Greptile}

[scodge-24]

@greptile review

[scodge-24]

@greptile review