---
name: jacobobryant-biff-spec-review
description: "Review the spec and enumerate unimplemented parts and open questions."
license: "MIT"
metadata:
  decimalai-skill-id: "d7d9dfa6-c55c-45f2-b67b-d6baa88c6df4"
  decimalai-version-id: "fbe7c6bd-f5ea-4e5a-b69b-8e276c20a47b"
  decimalai-version: "1"
  decimalai-body-sha256: "e6dda7fd7cf222f855c62375adbb40cf075efbaaebb394e79188fa7d22540227"
  decimalai-name: "jacobobryant/biff-spec-review"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "productivity"
  decimalai-source: "https://app.decimal.ai/s/jacobobryant-biff-spec-review@1/SKILL.md"
---
Review the `spec/` folder. When invoking this skill, the user may have
instructed you which parts of the spec to review. Otherwise, if the spec has
uncommitted changes, review those. Otherwise, if the current branch has spec
changes that aren't on the main/master branch, review those. Otherwise, review
the entire spec.

Then create/overwrite two files:

- `spec/agent/plan.md`: a checklist of changes that need to be made to the
  codebase to bring it in line with the spec. Each item in the checklist
  includes file(s) and line numbers from the spec, formatted like `1. [ ]
  widgets should frobulate. [widget
  frobulation](/spec/features/widgets.md#frobulation?lines=12-14)`. Only include
  the anchor for subheadings. Group the items under headings for "Add",
  "Remove", "Change", and "Fix". Do not include any additional information. If
  there is nothing to implement, delete the file.

- `spec/agent/questions.md`: a numbered list of questions that the user should
  clarify (by editing the spec) before implementation. These should address
  things like contradictions, ambiguities, and under-specification. Include a
  recommendation with each question. Include files and line numbers similar to
  `plan.md`. If there are no questions, delete the file.

After you've updated those files, if there are items in both `plan.md` and
`questions.md`, then output this text to the user:

> spec/agent/plan.md has been updated with items from the spec that need to be
> implemented. See spec/agent/questions.md for a review of the spec. After
> you've updated the spec, say `update` and then I'll review the spec again. If
> my recommendations for all the open questions are good, run the biff-spec-dev
> skill to implement the spec.

Replace "run the biff-spec-dev skill" with the exact text for running that skill
in the current agent harness, e.g. "run `$biff-spec-dev`" for Codex, "run
`/biff-spec-dev`" for Claude, etc. Same for all the text snippets below.

If there are items in `plan.md` but none in `questions.md`, output this text:

> spec/agent/plan.md has been updated with items from the spec that need to be
> implemented. No open questions. If you update the spec, say `update` and then
> I'll review it again. Run the biff-spec-dev skill to implement the spec.

If there are are no items in `plan.md`, output this text:

> The codebase already conforms to the spec. If you update the spec, say
> `update` and then I'll review it again.

Before you start reviewing, take a snapshot of the spec by copying the `spec/`
folder to a temporary folder. If the user asks you to update the spec, take
another snapshot and compare (with `diff` etc) against the previous snapshot to
ensure you notice exactly what changed.

Keep lines in `plan.md` and `questions.md` to 80 characters or less. Put an
empty line between items in both files.