Implement Plan With Docs

Execute the feature plan at $ARGUMENTS to the letter. The plan is the spec — implement what it says, not what you think is better. The local documentation corpus (output/docs/, output/repos/) is available as a safety net to resolve ambiguities or catch plan errors, but proactive corpus searching is not the primary activity.

Process

1. Parse the plan — read $ARGUMENTS as a file path. If the path does not point to an existing file, try prepending feature_plans/. Read the plan and extract:

   • Implementation steps — numbered headings under ## Implementation Steps (e.g., ### 1. Step Name)
   • Commit boundaries — steps whose name contains "Commit" or verification blocks labeled "After commit N"
   • Verification commands — code blocks under ### Verification commands or **After commit N** sections
   • Prescriptive gotchas — entries in ## Gotchas & Warnings tagged (prescriptive → Step N). Each maps to a specific implementation step.
   • Code patterns — the ## Code Patterns from Docs section, containing verbatim or adapted snippets to follow
   • Gaps — anything flagged **NOT IN LOCAL DOCS**
   • E2E test protocol — commands under ### Before/after live test, ### Manual smoke test, or similar ## Testing Strategy subsections. Extract the concrete commands and their expected outcomes (metrics to check, output to verify).
   • Pre-commit baselines — any test protocol items that require measurements on the unmodified codebase (e.g., "run before the commit", "before/after delta", "baseline comparison"). These cannot be captured after implementation begins.

   Create tasks to track each implementation step, each commit boundary, and the e2e test protocol (if present). Summarize the plan structure to the user: N steps, M commits, any gaps.

2. Pre-implementation scan — before writing code, read every file the plan says to create or modify. Verify they exist and match the plan's assumptions (function signatures, line numbers, import structures). Check that modules the plan imports from actually exist. If reality has drifted from the plan (e.g., a function was renamed, a line number shifted), note the drift and determine how to adapt while preserving intent. This is the earliest opportunity to catch stale plans — flag any drift to the user before proceeding.

   Run pre-commit baselines. If step 1 extracted pre-commit baselines, run them now on the unmodified codebase. Record the commands and their output — these measurements are destroyed once implementation begins and cannot be recaptured. Report the baseline results to the user before proceeding to step 3.

3. Implement each step — walk through the plan's implementation steps in order. For each step:

   • Read the step's full description, code patterns, notes, and source references from the plan
   • Identify target files; Read any you have not already read
   • Implement using Write (new files) or Edit (modifications)
   • Follow the plan's code snippets as closely as possible — ruff-compliant formatting differences are acceptable, but structural changes are not
   • When a step references a code pattern from the ## Code Patterns from Docs section, use that pattern
   • When a step says "same pattern as X" or "follow the existing convention" without giving explicit code, search the codebase or corpus to find the referenced pattern (this is ambiguity resolution, not deviation)
   • After multi-file steps, run ruff check on the modified files
   • When implementing a step that has a corresponding prescriptive gotcha, verify the gotcha is addressed in your implementation
   • Mark each task as completed as you finish each step

4. Consult the corpus when needed — search the local documentation corpus in exactly two situations:

   Ambiguity resolution — the plan references a pattern, convention, or API without giving the exact code. Search output/docs/ or output/repos/ to find it. Use Grep or Read for simple lookups. Use python -m shared.index search "<terms>" for broader searches. This is completing the plan, not challenging it.

   Contradiction detection — during implementation, you encounter a concrete mismatch between the plan and observable reality. Examples: wrong function signature, missing module, incorrect import path, API that doesn't accept the arguments the plan specifies. When this happens:

   1. Verify the ground truth — Read the actual file, search the docs
   2. Classify the mismatch:
      • (a) Minor adaptation — typo, import path, signature drift, off-by-one line number. The plan's intent is clear; only the surface detail is wrong.
      • (b) Architectural conflict — the plan's approach is fundamentally incompatible with the actual codebase structure. A design decision needs to change.
   3. For (a): fix while preserving intent. Note the adaptation in the completion report.
   4. For (b): launch a doc-researcher agent to gather comprehensive corpus evidence. Include the specific contradiction in the agent prompt. Based on the evidence, either:
      • Proceed with a justified deviation — but you must cite the corpus file(s) that justify it and note the deviation prominently in the completion report
      • Stop and ask the user — if the evidence is ambiguous or the deviation would change the plan's architecture

   The bar for deviation is high. The plan was built from corpus evidence and reviewed. "I think X is better" is not evidence. A deviation requires: (1) a concrete mismatch with observable reality, and (2) a cited corpus file or code observation that proves the plan wrong.

   Do not proactively search the corpus before each step. The plan is the spec. The corpus is the safety net.

5. Verify and commit at plan boundaries — when you reach a commit boundary defined in the plan:

   1. Run pip install -e ".[dev]" if pyproject.toml was modified since the last install
   2. Run every verification command from the plan's verification block for that commit, in order
   3. If any command fails: diagnose the failure, fix the specific issue, re-run verification. Maximum 3 fix-verify cycles per failure — if still failing after 3 attempts, stop and report the failure to the user
   4. Stage all files created or modified since the last commit
   5. Commit with a descriptive message following the repo's conventions: imperative mood first line, detail in body, Co-Authored-By trailer
   6. Push to remote

6. Final verification — after all commits, run the full test suite one last time:

   bash
   1pytest -v
   2ruff check .

   Then run the plan's e2e test protocol if one was extracted in Step 1. This means executing every command from the manual smoke test or live test section, verifying the expected outcomes (pages discovered, output files created, content correctly converted, sync-mode skips, etc.). --help checks verify wiring; e2e tests verify the feature actually works. Both are required when the plan specifies them.

7. Completion report — output directly to the conversation:

   ## Implementation Report: <plan title>
   
   ### Steps Completed
   - Step 1: <name> — done
   - Step 2: <name> — done
   ...
   
   ### Commits
   - `<hash>` <first line of commit message>
   - `<hash>` <first line of commit message>
   
   ### Verification Results
   - Commit 1: pytest N passed, ruff clean, [specific checks] OK
   - Commit 2: pytest N passed, ruff clean, [specific checks] OK
   
   ### Deviations
   None. Plan implemented as specified.
   — OR —
   - **Step N: <description>** — <what changed and why>
     Evidence: <corpus citation or code observation>
   
   ### Pre-Commit Baselines
   None required by plan.
   — OR —
   - **<protocol item>**: <recorded output/metrics from unmodified codebase>
   - **Post-commit comparison**: <delta vs. baseline>
   
   ### Gaps Encountered
   <If plan flagged NOT IN LOCAL DOCS gaps, note whether they were hit>
   

Critical Rules

1. The plan is the spec. Implement what it says. Do not redesign, optimize, or "improve" unless demonstrably wrong with corpus evidence.
2. Commit at the plan's boundaries, not yours. The plan groups changes into independently revertable units. Do not commit early or merge commit boundaries.
3. Run verification before every commit. Never commit without passing the plan's verification commands.
4. Fix forward, not sideways. When verification fails, fix the specific failure. Do not refactor adjacent code to "prevent" the problem.
5. Deviations require evidence. A cited corpus file or concrete code observation. Not opinion.
6. Stop on architectural conflicts. If the plan's approach is fundamentally incompatible with the codebase, stop and report to the user. Do not silently redesign.
7. Never skip a step. If a step seems redundant or already done, verify explicitly (Read the file, check the code). Note "already present" in the report if confirmed.
8. Track prescriptive gotchas. Each prescriptive gotcha maps to a specific implementation step. When implementing that step, verify the gotcha is addressed. A missed gotcha is a bug.