wiki-ingest

/sdd:wiki-ingest

You are ingesting SDD artifacts into the repo-scoped wiki: Compile once, maintain forever.

The wiki is a persistent, compounding artifact that sits between the user and raw source sessions. Every ingest enriches it. Never write without confirmation.

---

Input

One argument is required: --preliminary or --final. Optional: --title "<title>" to override the auto-derived title.

If neither mode is passed, stop and ask the user which mode they intend.

---

Step 1 — Initialize the wiki (idempotent)

Run the init helper to ensure .wiki/ exists with index.md, log.md, and CLAUDE.md:

bash "${CLAUDE_SKILL_DIR}/scripts/wiki-init.sh"

This is safe to re-run — it preserves existing content and only creates missing files.

---

Step 2 — Collect the artifacts from context

For --preliminary mode, gather from the current session:

• The spec produced by /spec (look in conversation history for the ### Functional Specification block)
• The plan produced by /plan (look for ### Technical Plan)
• The tasks summary (the numbered task list presented before the GitHub issue was created)
• The PR number and branch name (run gh pr view --json number,headRefName,title,url from the current branch)

For --final mode, gather:

• The PR number and merge status (gh pr view --json number,headRefName,state,mergedAt,url,body,comments)
• The preliminary wiki page for this PR (find by matching pr_number: in frontmatter across .wiki/*.md)
• Any review findings from /review outputs in conversation
• Post-review commits on the branch (git log --oneline <review-commit>..HEAD if applicable)
• User's stated lessons learned for this change (prompt if missing)

If key artifacts are missing, stop and ask the user to paste them rather than fabricating content.

---

Step 3 — Confirm with the user

Present a preview before writing. Show:

• Each page about to be created, with filename and title
• Target paths (e.g. .wiki/spec-2026-04-17-wiki-integration.md)
• Whether any filename collides with an existing page

Ask explicitly: "Proceed with ingestion?" Wait for confirmation. If the user declines, exit cleanly — nothing written.

---

Step 4 — Check for secrets

Scan the artifacts for secret-like strings before writing. Use the same pattern from skills/ship/scripts/pre-ship-check.sh:

echo "<content>" | grep -iE '(api_key|secret_key|password|token|credential).*=.*['\''"][^'\''"]{8,}'

If matches are found, show them to the user and ask whether to proceed or sanitize first.

---

Step 5 — Handle collisions

For each target filename, check if it already exists. If yes, ask the user to pick:

• Overwrite — replace the existing page.
• Variant — suffix the filename with -2, -3, etc. (use the lowest free number).
• Cancel — skip this page.

Never silently overwrite.

---

Step 6 — Generate deterministic filenames

Format: {type}-{YYYY-MM-DD}-{slug}.md

• type: spec, plan, tasks-summary, review-findings, lessons
• date: today's date in ISO format (date +%Y-%m-%d)
• slug: kebab-case of the title, ≤40 chars, lowercase, alphanumeric + hyphens only

slug=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/--*/-/g; s/^-//; s/-$//' | cut -c1-40)

---

Step 7 — Write each page with frontmatter

Every page must begin with YAML frontmatter:

---
type: spec | plan | tasks-summary | review-findings | lessons
title: <human title>
slug: <slug>
date: YYYY-MM-DD
pr_number: <N | null>
branch: <feat/N-name | null>
related: [<sibling-filename.md>, ...]
keywords: [<kw1>, <kw2>, <kw3>]
source_session: <optional short descriptor>
stage: preliminary | final
---

Pick keywords that future sessions would grep for — 3-8 terms, lowercase.

related rules:

• In --preliminary mode: link all pages from the same ingestion to each other (spec ↔ plan ↔ tasks-summary).
• In --final mode: link the new pages to the preliminary page found in Step 2.

Body content: paste the artifact verbatim, preserving any Given/When/Then blocks and numbered lists. Translate to English if the source is in another language — wiki content is English per .claude/rules/git-conventions.md.

---

Step 8 — Update .wiki/index.md

Append each new page to the correct H2 section (## Specs, ## Plans, ## Tasks Summaries, ## Review Findings, ## Lessons). Entry format:

- [<title>](<filename>) — <one-line summary> (<YYYY-MM-DD>, PR #<N>)

If the H2 section is missing (old .wiki/ predating this skill), add it in the correct order.

---

Step 9 — Append to .wiki/log.md

Add an entry at the end:

## [YYYY-MM-DD] <stage> | <title>
- Ingested: <filename1>, <filename2>
- PR: #<N>
- Branch: <branch-name>
- <optional one-line note about what triggered this ingest>

---

Step 10 — Confirm

Report back to the user:

✓ Wiki updated — <stage> ingestion for PR #<N>
  Pages written: <list>
  Index sections updated: <list>
  Log entry appended.

Do NOT automatically commit. The user controls when to commit wiki changes.

---

Gotchas

• Writing before confirmation. The most common failure. Never skip Step 3. A declined prompt means: exit cleanly, touch nothing.
• Fabricating missing artifacts. If the spec or plan isn't in context, stop and ask. Do not invent content to fill the page.
• Silent overwrites. Collisions must prompt the user. Never blindly replace an existing page.
• Writing in the user's language. Wiki content is English. If the spec was written in Spanish, translate before ingesting.
• Skipping frontmatter. Without frontmatter, matching and cross-referencing break. Every page must have complete frontmatter.
• Missing keywords. The keywords: field drives wiki-query.sh rankings. Three to eight relevant terms, not zero.
• Ingesting partial final data. For --final, if the PR isn't merged yet, warn the user. A final page implies the change is done.
• Editing the wiki without using this skill. Other skills (/ship, /wiki:close-loop, /spec, /plan) must delegate here, not write to .wiki/ directly.

---

Important constraints

• Never write without explicit user confirmation. Opt-in is the entire point.
• Never delete wiki pages from this skill. Deletion is a separate, manual action.
• Never commit changes. The user owns git state.
• Absence of .wiki/ is not an error — Step 1 creates it.
• All wiki content must be in English.
• Follow .claude/rules/wiki-conventions.md for any detail not covered here.

---

References

• Conventions: .claude/rules/wiki-conventions.md
• Helper scripts: scripts/wiki-init.sh, scripts/wiki-query.sh
• Callers: /ship Step 9 (preliminary), /sdd:wiki-close-loop (final)