Name: Foundry Review
Author: danhannah94

Foundry Review — Annotation Conventions

When refining or reviewing a document in Foundry, follow these conventions for annotations. This skill is invoked automatically by /refine when the target is a Foundry doc.

Annotation principles

Always highlight text. When creating an annotation, use quoted_text to reference the specific text you're commenting on. Annotations without highlighted text are harder to trace back to the content.
Prefer many short comments over few long ones. Each comment should address ONE concern. Don't bundle 5 questions into a single annotation — they'll get tangled in the reply thread.
Use threads for back-and-forth. Reply to annotations using parent_id rather than creating new top-level annotations. Keep the conversation attached to the original concern.
Resolve when agreed. Once both parties agree on the resolution, use resolve_annotation. Don't leave resolved items as submitted — it clutters the view.

Foundry Review — Annotation Conventions

When refining or reviewing a document in Foundry, follow these conventions for annotations. This skill is invoked automatically by /refine when the target is a Foundry doc.

Annotation principles

Always highlight text. When creating an annotation, use quoted_text to reference the specific text you're commenting on. Annotations without highlighted text are harder to trace back to the content.
Prefer many short comments over few long ones. Each comment should address ONE concern. Don't bundle 5 questions into a single annotation — they'll get tangled in the reply thread.
Use threads for back-and-forth. Reply to annotations using parent_id rather than creating new top-level annotations. Keep the conversation attached to the original concern.
Resolve when agreed. Once both parties agree on the resolution, use resolve_annotation. Don't leave resolved items as submitted — it clutters the view.

Context	Focus	Tone
Design doc refinement	Architecture, scope, assumptions, risks	Challenging — poke holes
Story review	Acceptance criteria, completeness, clarity	Precise — is this implementable?
QA report	Evidence, coverage, edge cases	Factual — show the receipts
Code review (via Foundry)	Intent, approach, alternatives	Constructive — suggest, don't just criticize

Foundry Review

Foundry Review — Annotation Conventions

Annotation principles

Foundry Review

Foundry Review — Annotation Conventions

Annotation principles

Review workflow

Annotation types by context

Anti-patterns

Notion

Feishu Wiki

Gemini

Obsidian Vault Maintainer

Openclaw Pr Maintainer

Wiki Maintainer