Skip to main content

Workflows: Review Workflow

A review workflow uses Knot to automatically review documents as they change. This is one of the most common patterns — a knot watches a directory and critiques files using an AI agent.

Example: PRD Section Reviews​

In this example, we set up a loom that reviews different sections of Product Requirement Documents (PRDs).

1. Create a Profile​

rig/profiles/reviewer.md:

---
name: reviewer
provider: openai
model: gpt-4o
---

You are a thorough technical reviewer. Analyse documents
carefully and provide specific, actionable feedback.

2. Create the Loom​

mkdir -p rig/prd-review-loom

3. Create Review Knots​

Each knot reviews a different section. They share the same strand directory and profile.

Goals review — rig/prd-review-loom/goals-review.md:

---
name: goals-review
agent-profile-ref: reviewer
strand-dir: "project/prds"
---

Review the goals section of this PRD. Check that:
- Each goal is specific and measurable
- Goals align with the problem statement
- Success criteria are defined

Non-goals review — rig/prd-review-loom/non-goals-review.md:

---
name: non-goals-review
agent-profile-ref: reviewer
strand-dir: "project/prds"
---

Review the non-goals section. Check that:
- Scope boundaries are clearly defined
- Exclusions are justified

4. Trigger Reviews​

Place a PRD in project/prds/:

cat > project/prds/my-feature.md << 'EOF'
# My Feature PRD

## Goals
- Improve load time by 50%
- Reduce server costs

## Non-Goals
- Mobile app support
- Internationalisation
EOF

Both knots trigger on this file change. Each reviews its assigned section and appends feedback to its tie-off file.

5. Review the Results​

Read the tie-off files:

cat rig/tie-offs/prd-review-loom/tie-off-goals-review.md
cat rig/tie-offs/prd-review-loom/non-tie-off-goals-review.md

Or check the rig state:

cat rig/state.json | python3 -m json.tool

For a structured quality review of the rig's output, use the knot-manage skill. It examines tie-off files, assesses output quality, checks idempotency, and traces producer→consumer interaction chains to verify communication was effective.

Idempotent Reviews​

Reviews should be idempotent. If the same file is reviewed twice (e.g. after a minor edit), the knot should produce a fresh review — not duplicate previous feedback. Since tie-off files are append-only, each run adds a new section. The knot's instructions should focus on reviewing the current state of the document, not accumulating feedback.

Good instructions:

Write these in the knot's markdown body (after the closing ---):

Review the goals section of this document.
Provide feedback on the current content only.

Avoid instructions that say "add to previous feedback" or "continue where you left off" — these break idempotency.

See Also​