Code skills

Document and review what was built

Two skills for an existing implementation. One writes technical documentation, the other reviews the code. They work from the code and your project conventions, so you can run them on any feature, whether or not it went through the six phases.

Not installed yet? Install speccen first.

Code documentation Code review

Code documentation

/speccen:code-documentation

It asks for the feature or component name, then works in two gated phases. The Architect decides at each gate, and the AI never moves on by itself.

  1. Planning

    You set the scope and boundaries. The AI reads your project conventions, optionally analyzes the code, and proposes a documentation outline.

    You approve the plan or send feedback

  2. Generation

    The AI writes the full document, with diagrams, examples and service contracts.

    You approve it or ask for revisions

Output goes to .speccen/documentation/<id>/, where <id> is YYYY-MM-DD.<name_snake_case>. The authored source and deliverable is <name>_documentation.html. Next to it, <name>_documentation.md holds the workflow state and prompt log, and becomes a reduced Markdown copy after generation. Run it again for the same feature and it resumes from that state. At each phase transition it commits to git when git is configured.

Code review

/speccen:code-review

It asks for the feature or refactoring name, finds a matching <name>_analysis.md document if there is one, and reviews the current state of the code. It does not care who wrote it.

  • With an analysis document or a speccen bundle, the code is checked against that blueprint.
  • Without one, it reviews against your project conventions, security basics and code quality.
  • It reads the git changes since implementation started and reports a structured Review Report.

Reports are saved as .speccen/reviews/<id>/<name>_review_<YYYYMMDD_HHMMSS>.md. Repeat reviews of the same feature accumulate in one folder, told apart by the timestamp.

Afterwards it offers to turn the findings into GitHub Issues. Nothing is created until you have seen a confirmation summary and agreed. It uses the gh CLI.

Claude Code also has a built-in /code-review. This one is speccen:code-review. Type speccen in the command picker to pick the right one.

Inside or beside the workflow

These two skills do not need a speccen bundle. Inside the six phases, the optional Retrospective (07) and Reference (08) pass cover similar ground from the bundle. Reach for the code skills when there is no bundle: older code, a pull request from a colleague, or a feature built outside the workflow.