# Guide items

Project-agnostic best-practice notes on a technology or framework.

**Lifecycle:** Draft → Published → Deprecated

## Commands

```bash
sq create guide "…" --author architect [--tech …] [--tag …]
sq guide <n> status Published
```

## For Robert Architect (`architect`)

**Enter** — before you act:
- Read the full item dossier: `sq guide <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- identify the recurring practice or anti-pattern worth capturing

**Do:**
- author it (`sq create guide "…" --author architect --tech …`)
- write good practice + anti-patterns in the body

**Hand off:**
- when the first draft is complete, `@tech-writer` to polish; set `sq guide <n> status Published` once it's clean

## For Olivia Lead (`tech-lead`)

**Enter** — before you act:
- Read the full item dossier: `sq guide <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- spot a lesson from a real task worth generalising

**Do:**
- co-author the guide drawn from concrete work

## For Theo Writer (`tech-writer`)

**Enter** — before you act:
- Read the full item dossier: `sq guide <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- read the draft guide

**Do:**
- edit for clarity, structure, and currency

**Hand off:**
- `sq guide <n> status Published` when it's clean

**Watch for:**
- keep it project-agnostic; deprecate guides that go stale

---
The `.md` files are sq-managed — never edit them by hand. Items are addressed as
`sq guide <n> <verb>`. Set this item's body with `sq guide <n> body
-m "…"` (or `--file`); `--desc` sets only the short summary. Its user stories / subtasks / findings
get their bodies from `sq guide <n> <kind> <k> body -m "…"`. Read anything back with
`sq guide <n> show --full --comments` (full dossier, including discussion) /
`sq guide <n> <kind> <k> show`.
