finish-work

Files (1)

• SKILL.md

SKILL.md (first lines)

# Finish work

Work is complete only when steps 1 to 7 below are done, in order. Step 8
comes after the merge. The commands for each step come from the
repository's `AGENTS.md` under `## Commands`. If a step cannot run, say so,
name the blocker, and list the checks that did run.

## 1. During development

- Run only the tests that cover the change. Require a 100% pass rate for the
  tests that run.
- Run each new asynchronous or browser test 10 times before the commit,
  as the `testing` skill says.
- Run the early repository check (format, lint, file length, exports) early,
  before long test runs.
- Leave complete unit and browser suite runs to the complete gate.
- When you add a feature, run a smoke test: start the server, run the
  command, open the page. Do this before the gate.

## 2. The complete gate

- Run the complete gate once before you say work is complete.
- A local run usually stops at the first failed suite. After a failure, fix
  it. Rerun only the failing tests, or the failed suite. Then rerun the
  complete gate.
- Any selected test run, filtered run, or single suite is partial
  verification. Only the complete gate proves the work.
- If a test that the diff does not touch fails and then passes on a rerun,
  it is an unrelated flaky test. Do not fix it in this branch. Report it
  under the rules in the `deterministic-tests` skill.
- A flaky test that the diff adds or changes may be fixed without asking
  only under the flaky-test rule in the `deterministic-tests` skill.
- Documentation-only or plan-only changes, including initial plan creation,
  do not require the gate. Validate the changed Markdown and review the diff
  instead. For a plan with a new decision, run the options check over it,
  as the `plans` skill says.

## 3. Keep the spec aligned

- Docs, protocol docs, mockups, and every `README.md` are part of the spec.
  Update them in the same change. A protocol doc changes only when a
  requirement or a decision changes. A README changes when an entry point
  or the public behaviour changes. See the `documentation` skill.
- Tick completed plan TODOs and add discovered TODOs. See the `plans` skill.
- When the change removes or renames anything, search `docs/`, `plans/`, and
  every `README.md` for its name and update live references. See the
  `git-commit` skill.

## 4. Commit and push

- Commit with the `git-commit` skill: run its deletion audit before and
  after the commit, run `git add -A` so that newly created files are
  tracked, and write a Conventional Commits message. Then push the branch.
- If the branch needs a merge or rebase first, follow the `git-merge`
  skill.
- A new plan gets no pull request in this step. Step 6 says when it
  opens. See the `plans` skill.

## 5. Review

- After the push, review the complete local diff against `origin/main` with
  the `implementation-review` skill. Review a branch that targets a primary
  branch against that branch instead. The review itself is read-only. Its
  findings stay in the diff unless the user explicitly asked for a wider
  review.
- Record each round in the findings file of the branch, as the
  `implementation-review` skill says.
- Before each fix round, run the finding checks of the
  `implementation-review` skill: one check for each new finding. Each
  check confirms its finding, finds its links, and checks its options. A
  finding that is not real or not in the scope is removed. The check
  corrects a wrong severity or category in place.
- Apply the review-fix rule. Make the final call on the outcome of each
  confirmed finding, with the merged options. Fix the findings with
  `Action: fix now`, with the option that each names. Record a follow-up
  item for each other finding and for each wider fix that you split off,
  as the `plans` skill says. Run the checks. Commit and push. Re-review
  once. Then stop the fix rounds and go on to step 6.

## 6. Pull request

- The implementation is complete when steps 1 to 5 are done. When the
  change has a plan, the implementation is complete only when the plan's
  other milestone TODOs are also ticked. A new plan has unticked
  milestone TODOs, so it is not complete. Open findings that wait for the
  user do not make the implementation incomplete.
- When the change has a plan, read "Deleting the plan" in the `plans`
  skill before you open the pull request. It says when the plan goes,
  when it stays, and the steps.
- Open the pull request when the implementation is complete, or when the
  user asks for it. Before that, report the branch. Write the title and
  the description with the `git-commit` skill. The description lists each
  follow-up item that the change adds, so that the user can bring one
  back into the branch before the merge.

## 7. Report

Write the final message in Simplified Technical English, with the layout
and labels in the `decisions-and-findings` skill. Include:

- Each item that still needs the user's answer, also an item from an
  earlier message. Name it in the first sentence. Give it in full, as
  "Open items" in the `decisions-and-findings` skill says.
- What changed, the commit, and the branch or the pull request.
- The checks that ran and their results. Name any check that was skipped or
  could not run, and why.
- The test cost of the change: each test that it adds or removes, with its
  run time, as the `testing` skill says.
- The fixed review findings, the deferred findings and wider fixes with
  their follow-up items, and the findings that need a decision, each with
  a recommendation. Keep them in three lists.
- The number of open follow-up items in the repository.
- The follow-up items of the blocked wider fixes, one line per class.
- Problems outside the review scope, for a separate branch. An unrelated
  flaky test gives its name, failure text, rerun outcome, and suspected
  source.
- Open plan TODOs.

## 8. After the merge

From futex-ai/skills, MIT.

More from futex-ai/skills