arn-code-document-project

Arness Document Project

Generate developer documentation for a completed feature or bug fix by reading plan artifacts, spec files, execution reports, and git diff to produce accurate, reference-heavy documentation.

Pipeline position:

arn-code-execute-plan -> arn-code-review-implementation -> **arn-code-document-project** -> arn-code-ship

This skill produces a single documentation file (or directory for complex projects) that captures what was actually built, how it diverges from the original plan, and where to find everything in the codebase.

Workflow

Step 1: Load Configuration

1. Read the project's CLAUDE.md and extract the ## Arness section to find:
   • Plans directory -- base path where project plans are saved
   • Specs directory -- path to the directory containing specification files
   • Code patterns -- path to the directory containing stored pattern documentation
   • Docs directory -- path to the directory where documentation is written
2. Template version check: If Template version and Template updates fields are present in the ## Arness section, run the template version check procedure from ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-save-plan/references/template-versioning.md before proceeding. If these fields are not present, treat as legacy and skip.
3. Ask for PROJECT_NAME if not provided in the trigger message.
4. Verify the project directory exists with reports: <plans-dir>/<PROJECT_NAME>/reports/
5. If Docs directory is not in config, default to .arness/docs/

---

Step 2: Read Plan Artifacts

Read these files from <plans-dir>/<PROJECT_NAME>/:

1. INTRODUCTION.md -- project overview, goals, key decisions
2. SOURCE_PLAN.md -- original implementation plan
3. All phase plans in plans/PHASE_*.md -- acceptance criteria, expected files
4. All reports in reports/ -- implementation reports, testing reports
5. PROGRESS_TRACKER.json -- overall completion status (if it exists)

If reports are missing, warn the user that the project may not have been fully executed yet and:

Ask (using AskUserQuestion):

"Some reports are missing. The project may not have been fully executed yet. Proceed with available data?"

Options:

1. Yes, proceed -- Generate documentation from the available data
2. No, stop -- Run execution first before generating documentation

---

Step 3: Read Specification

Find the original specification:

1. Check SOURCE_PLAN.md for a Spec: line referencing the spec file path
2. If not found, try name-matching files in <specs-dir>/ against the project name
3. If found, read the spec to extract: problem statement, key decisions, scope, components

If no spec is found, proceed without it (some projects may not have specs).

---

Step 4: Analyze Git Diff

If Git is available (check ## Arness config or run git rev-parse --is-inside-work-tree):

1. Determine the default branch (git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@', falling back to main), then find the merge base: git merge-base HEAD <default-branch>
2. Get change summary: git diff --stat <merge-base>..HEAD
3. Get file status: git diff --name-status <merge-base>..HEAD

Focus on key entry points -- don't read every changed file. Prioritize:

• New files (Added status)
• Core implementation files (models, services, API endpoints, configuration)
• Test files (for test coverage summary)

If Git is not available, skip this step and rely on report data only.

---

Step 5: Identify Divergences

Compare what was planned (INTRODUCTION.md, phase plans, spec) with what was built (reports, git diff):

• Features planned but not implemented
• Features implemented differently than planned
• Additional features not in the original plan (scope additions)
• Bugs found and fixed during testing (from bugsFixed in reports)
• Different architectural approaches than specified

---

Step 6: Generate Documentation

Use the template from ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-document-project/references/doc-template.md.

Single file for simple projects (fewer than 15 changed files AND 3 or fewer phases):

• Write to <docs-dir>/<PROJECT_NAME>.md

Directory for complex projects:

• Write to <docs-dir>/<PROJECT_NAME>/README.md with subtopic files as needed

Doc name is derived from the project name (lowercase, hyphens).

---

Step 7: Verify and Report

After writing:

1. Verify all file paths referenced in the documentation actually exist
2. Verify class/function names mentioned are accurate
3. Report to the user:
   • Documentation location and file(s) created
   • Key divergences found (plan vs reality)
   • Any gaps or concerns (e.g., missing reports, incomplete spec)

Suggest next step: "Run /arn-code-ship to commit your changes and create a pull request."

---

Error Handling

• ## Arness config missing in CLAUDE.md -- inform the user: "Arness is not configured for this project yet. Run /arn-implementing or /arn-shipping to get started — it will set everything up automatically."
• Project directory missing -- suggest running /arn-code-save-plan and /arn-code-execute-plan first.
• Reports directory empty -- suggest running /arn-code-execute-plan to generate reports.
• Docs directory does not exist -- create it with mkdir -p.
• Git not available -- skip git diff analysis, rely on report data only.