Wiki Ingest

Detect which synthesis pages are affected when an asset is added or changed, then report staleness or draft updated content.

Input

Accept one of the following:

• Asset path (e.g., shared/prompts/k8s-log-analyzer.md)
• Asset ID (e.g., k8s-log-analyzer)

Optional argument: --draft-pr to switch from report mode to draft-PR mode.

Report Mode (default)

When no --draft-pr argument is provided, produce a read-only impact report.

Steps

1. Resolve the asset. Read metadata.json at the repository root. Locate the entry whose id or file_path matches the input. Extract the asset's id, tags, last_reviewed date, and domains (derived from all tags in the tags array; an asset with multiple tags appears in multiple domains).

2. Find affected synthesis pages. Read every Markdown file under docs/synthesis/. For each file, parse its YAML frontmatter and look for a sources array. Collect every synthesis page whose sources list contains the resolved asset ID.

3. Check staleness. For each affected synthesis page, compare its last_synthesized frontmatter date against the asset's last_reviewed date. If last_synthesized is older than last_reviewed, mark the page as stale and note the number of days behind.

4. Check domain coverage gaps. Using metadata.json, group all assets by domain (all tags; assets with multiple tags appear in multiple domains). For each domain that has 3 or more assets, check whether a corresponding entity page (entity-{domain}.md) exists in docs/synthesis/. If no entity page exists, flag the domain as a coverage gap.

5. Produce the report. Output a structured summary with these sections:

   • Resolved Asset: ID, path, last_reviewed date
   • Affected Pages: list of synthesis page paths with staleness status (fresh/stale + days)
   • Coverage Gaps: domains meeting the 3-asset threshold that lack entity pages
   • Suggested Actions: concrete next steps (e.g., "Re-synthesize docs/synthesis/kubernetes-tools.md" or "Create entity page for domain 'terraform'")

Draft-PR Mode (opt-in)

When the --draft-pr argument is provided, create a branch and update affected pages.

Steps

1. Perform all report-mode steps above to identify affected pages and gaps.

2. Create a worktree branch. If the repository uses a worktree-based workflow (check CLAUDE.md), create a worktree:

   git worktree add worktrees/wiki-ingest-{asset-id} -b wiki-ingest/{asset-id} main
   cd worktrees/wiki-ingest-{asset-id}
   

   Otherwise, create a branch: git checkout -b wiki-ingest/{asset-id}. Replace {asset-id} with the resolved asset ID.

3. Update affected synthesis pages. For each stale synthesis page:

   • Re-read all source assets listed in the page's sources frontmatter.
   • Regenerate the page body by synthesizing the current content of those source assets. Preserve the existing page structure (headings, sections) but refresh facts, descriptions, and cross-references.
   • Update the last_synthesized date in frontmatter to today's date.

4. Create new entity pages for any coverage gaps identified in step 1. Use the synthesis page template from docs/synthesis/README.md if available.

5. Commit and push.

   git add docs/synthesis/
   git commit -m "docs(synthesis): refresh pages for {asset-id}"
   git push -u origin wiki-ingest/{asset-id}
   

6. Create a draft PR.

   gh pr create --draft \
     --title "docs(synthesis): refresh pages for {asset-id}" \
     --body "Auto-generated by wiki-ingest skill.
   
   ## Updated Pages
   - (list each updated synthesis page path)
   
   ## New Pages
   - (list each newly created entity page, or 'None')
   
   ## Source Asset
   - {asset-id} (last_reviewed: {date})"
   

7. Report what was updated. Output the PR URL and a summary of all changes made.

Key Files

File	Purpose
metadata.json	Asset registry with IDs, paths, tags, dates
docs/synthesis/README.md	Synthesis page index and templates
docs/synthesis/*.md	Individual synthesis pages with sources and last_synthesized frontmatter