tkstang/oat-docs-apply

Docs Apply

Generate or update documentation files from a docs analysis artifact, with explicit approval and branch-based workflow.

Prerequisites

• A recent docs analysis artifact in .oat/repo/analysis/.
• If no analysis exists, run oat-docs-analyze first.
• jq available in PATH for tracking updates.
• gh available if a PR should be opened automatically.

Mode Assertion

OAT MODE: Docs Apply

Purpose: Apply approved documentation changes derived from a docs analysis artifact.

BLOCKED Activities:

• No unapproved documentation changes.
• No branch creation before the recommendation plan is reviewed.
• No changes outside the documentation scope except deterministic nav sync and tracking updates.

ALLOWED Activities:

• Reading analysis artifacts and the current docs surface.
• Creating or updating docs files and mkdocs.yml when approved.
• Running oat docs nav sync after approved structural changes.
• Creating branches, commits, and optional PRs.

Analyze vs Apply Boundary

Treat the docs analysis artifact as the source of truth for what should be changed and why.

Apply may:

• read the exact evidence sources cited by the artifact
• verify that cited files still exist
• translate approved recommendations into concrete docs changes

Apply must not:

• invent unsupported docs conventions
• infer structure or migration rules from defaults or a tiny sample
• create new recommendations that are not present in the artifact
• silently fill in missing evidence gaps

Self-Correction Protocol: If you catch yourself:

• Editing docs outside approved recommendations -> STOP and remove the extra change from the work plan.
• Applying manual nav changes when oat docs nav sync should be used -> STOP and switch to the CLI helper.

Recovery:

1. Return to the approved recommendation list.
2. Re-apply only approved docs changes and deterministic nav sync.

Progress Indicators (User-Facing)

When executing this skill, provide lightweight progress feedback so the user can tell what’s happening.

• Print a phase banner once at start:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ OAT ▸ DOCS APPLY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Use step indicators:

  • [1/7] Loading analysis artifact…
  • [2/7] Building recommendation plan…
  • [3/7] Reviewing approvals…
  • [4/7] Creating branch…
  • [5/7] Applying docs changes…
  • [6/7] Running nav sync + verification…
  • [7/7] Committing, tracking, and summary…

Process

Step 0: Intake - Find Analysis Artifact

Locate the most recent docs analysis artifact:

ls -t .oat/repo/analysis/docs-*.md 2>/dev/null | head -1

If none exists, stop and instruct the user to run oat-docs-analyze.

Validate that each recommendation in the artifact includes:

• evidence
• confidence
• disclosure
• link targets when disclosure is link_only

If the artifact is missing that detail, stop and tell the user to re-run oat-docs-analyze.

Step 1: Build the Recommendation Plan

Read the analysis artifact and build the plan from its recommendations. Do not rediscover conventions from scratch during this step.

Common docs actions:

• Create missing index.md
• Add or repair ## Contents
• Convert overview.md usage to the index.md contract
• Add or update docs/contributing.md plugin guidance
• Scaffold an OAT docs app when no docs app exists
• Run oat docs nav sync after approved structural changes

Carry forward the artifact's evidence refs, confidence, disclosure mode, and link targets into the apply plan.

Coverage-gap recommendations may also be:

• omit
• ask_user

If evidence is missing, stale, or contradicts the current docs tree, stop and ask for a fresh analysis instead of guessing.

Use references/apply-plan-template.md and preserve the exact presented markdown as APPLY_PLAN_MARKDOWN for commit/PR summary use.

Step 2: Review the Plan with the User

Present the full recommendation plan first, then ask which review mode they want:

• apply all
• apply interactively
• discuss

For review-mode and follow-up decisions, use host-aware prompting:

• Claude Code: AskUserQuestion
• Codex: structured user-input tooling when available in the current host/runtime
• Fallback: plain-text questions

If the user chooses apply all:

• confirm the full plan
• capture any global notes that apply across the whole plan
• treat all non-blocked recommendations as approved unless the user names exceptions

If the user chooses apply interactively, ask for each recommendation:

• approve
• modify
• skip

If the user chooses discuss, answer questions, revise the plan if needed, and then ask again:

• apply all
• apply interactively
• discuss

If all recommendations are skipped, stop without changing files.

Build an APPLIED_PLAN_DETAILS block from approved or modified recommendations with:

• recommendation id
• action
• target path
• disclosure
• evidence refs
• decision (approved_via_apply_all / approved / modified)
• user notes

Step 3: Create Branch

After approvals:

TIMESTAMP=$(date -u +"%Y-%m-%d-%H%M")
BRANCH="oat/docs-${TIMESTAMP}"
git checkout -b "$BRANCH"

If branch creation fails because of unrelated local changes, ask the user to resolve that state before continuing.

Step 4: Apply Approved Changes

For each approved recommendation:

1. Read only the affected docs files and the evidence sources cited by the artifact.
2. Make targeted edits that satisfy the approved fix.
3. Preserve existing prose and only change the necessary sections.
4. Honor the disclosure mode from the artifact:
   • inline -> keep the essential guidance in the target page
   • link_only -> add a concise pointer to the canonical doc/config/example
   • omit -> do not encode the item in the docs change
   • ask_user -> require explicit user confirmation before writing

When approved actions involve docs app creation or nav updates:

• Use oat docs init for scaffolding when appropriate.
• Use oat docs nav sync instead of manually editing nav when the CLI helper can generate it.

Negative rules:

• Do not invent docs structure rules, migration rules, or plugin guidance not backed by the artifact's cited evidence.
• Do not inline large setup/config details when the artifact says link_only.
• Do not create replacement link targets if the artifact omitted them; stop and ask for a fresh analysis or user guidance.
• If a cited source no longer exists, stop that recommendation and ask for a fresh analysis or user guidance.

Step 5: Verify and Sync Navigation

Run the smallest relevant verification set based on what changed:

• oat docs nav sync
• pnpm --dir <docs-app> docs:lint (no-op when no linter is configured)
• pnpm --dir <docs-app> docs:format:check
• pnpm --dir <docs-app> docs:build

If no docs app exists yet, use file-level verification and confirm the structural contract manually in the summary.

Step 6: Commit and PR

Commit the approved changes:

git add {approved-files}
git commit -m "docs: apply approved docs recommendations"

Offer to open a PR:

After committing, proactively ask the user if they'd like to open a pull request. Frame this as the recommended next step:

Changes committed. Would you like me to push and open a pull request?
The PR will include the applied plan summary and the full analysis artifact for reference.

For the PR-choice prompt, use host-aware prompting:

• Claude Code: AskUserQuestion
• Codex: structured user-input tooling when available in the current host/runtime
• Fallback: plain-text questions

If creating PR:

1. Push the branch.
2. Create a PR with the structure below.
3. The PR body must include the full analysis artifact in a collapsible section at the bottom so reviewers can see the evidence behind every change.

git push -u origin "$(git rev-parse --abbrev-ref HEAD)"
gh pr create --base main \
  --title "docs: apply approved docs recommendations" \
  --body "$(cat <<'PRBODY'
## Summary

- Applied docs recommendations from analysis artifact
- Source: {analysis-artifact-path}
- Result: {N} created, {N} updated, {N} skipped

## Applied Plan

{APPLY_PLAN_MARKDOWN}

## Verification

- {commands run and results}

---

## Full Analysis Artifact

The complete analysis that produced these recommendations is included below for reviewer reference.

<details>
<summary>Click to expand full analysis</summary>

{full contents of the analysis artifact markdown file}

</details>
PRBODY
)"

If gh is not available or fails:

PR creation failed. To create manually:
1. Push: git push -u origin {branch}
2. Open PR at your repository's web interface
3. Use the structure above in the PR body, including the full analysis in a collapsible section

Step 7: Update Tracking and Output Summary

Update shared tracking:

TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
ROOT_TARGET=$(bash "$TRACKING_SCRIPT" root)
ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')

bash "$TRACKING_SCRIPT" write \
  docsApply \
  "$ROOT_HASH" \
  "$ROOT_BRANCH" \
  "apply"

Output:

Apply complete.

  Files created:   {N}
  Files updated:   {N}
  Files skipped:   {N}
  Docs target:     {path}
  Verification:    {commands run}

Next step: Re-run oat-docs-analyze if you want a post-apply verification artifact.

Deferred from v1

• Automatic content synthesis for missing topic pages
• Multi-docs-app fanout in one apply session
• Bulk conversion of legacy docs trees without user review

References

• Apply plan template: references/apply-plan-template.md
• Shared tracking helper: .oat/scripts/resolve-tracking.sh