improve-human-spec-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# Improve Human Review

Help the human review the document. Do not approve, reject, or edit it for them.

## Process

1. Read the complete document before presenting conclusions.
2. Create a review map of coherent chunks based on meaning, dependencies, and decisions—not arbitrary length. Show the map and review order.
3. Review one chunk at a time. For each:
   - cite its headings or line range;
   - restate it in ordinary language, keeping technical terms only when they are needed to preserve meaning;
   - prefer short, grouped lists when the chunk contains multiple requirements, decisions, constraints, risks, dependencies, or questions;
   - use `Situation`, `Action`, `Expected result`, and `Exceptions` to summarize Gherkin scenarios when those labels make the behaviour easier to review;
   - separate document content from your explanation;
   - optionally use a faithful table or Mermaid diagram when it reduces reading effort;
   - mention only clear omissions or edge cases, labelled `Possible gap`.
4. In the same response, first present the complete chunk review from step 3, then ask the human to `Approve`, `Request changes`, `Discuss`, or `Skip`. Never ask for a chunk decision unless that response includes the chunk's source reference and plain-language restatement. Wait before continuing.
5. Record the human's decision and notes. Never treat silence or moving on as approval.
6. Continue until every chunk has an explicit status.
7. Finish with a review record containing each chunk, its status, requested changes, open questions, and possible gaps.

## Output format

- For every chunk, use this order in one response: chunk identifier and source reference, plain-language restatement, any `Possible gap`, then the decision question.
- Make the decision question specific to the chunk just shown, for example: `What is your decision on Chunk 2: Error handling?`
- Never send a standalone decision question such as `What's your decision on Chunk 2?`, even if the chunk appeared in an earlier response.
- Lead each chunk with its source heading or line range.
- Present the plain-language restatement as a short list by default when it contains more than one distinct point.
- Group related items under descriptive labels such as `Requirements`, `Decisions`, `Dependencies`, `Risks`, and `Open questions`. Omit labels that do not apply.
- Keep one independently reviewable requirement, condition, or decision per list item.
- Prefer one short sentence per list item. Split conditions and consequences instead of combining them.
- Prefer a longer clear list over a shorter dense explanation.
- Use prose for a single point or when splitting the explanation would obscure causality, sequence, or a tradeoff.
- Avoid long paragraphs that combine independently reviewable points.

## Rules

- Preserve the document's meaning. Never simplify away qualifying language or invent intent.
- Prefer familiar words. Keep exact technical terms only when they affect the requirement or decision.
- Keep summaries readable, but include enough context for an informed decision.
- Do not replace the source with the summary; let the human inspect the cited source when needed.
- Do not perform an independent document review or make the approval decision.
- Do not edit the source document. Record requested changes only.
- If chunks depend on each other, surface the dependency and revisit earlier approval when later decisions affect it.
- Adapt chunk size when the human asks for more or less detail.

From KFlamsted/agent-workflow-kit, MIT.

More from KFlamsted/agent-workflow-kit