snorkel

reef:snorkel

Question-guided auto-discovery. Reads source code, uses the discovery question bank for direction, and produces 5-10 draft artifacts per source. No user input needed.

The key difference from a blind scan: snorkel reads the question bank and uses it to decide what to look at, what to document, and what to flag as unknown. Questions are the steering mechanism.

---

Context Loading

1. Find the reef root. Look for .reef/ in cwd or parent directories. If not found: "No reef found. Run /reef:init first."
2. Read .reef/project.json for project name, source paths, and service groupings. If no sources: "No sources configured. Run /reef:init to add source paths."
3. Read ${CLAUDE_PLUGIN_ROOT}/references/methodology.md — voice and personality.
4. Read .reef/questions.json — the discovery questions. These steer what you investigate and document.
5. Read existing artifacts in artifacts/ to avoid duplicates.

Resume detection

After loading context, check if snorkel has already partially run by comparing existing artifacts against what project.json services would produce:

• Count existing SYS-, SCH-, API-, CON-, GLOSSARY-, PROC-, RISK-, DEC-, PAT- artifacts
• Compare against the number of services and source repos configured

If artifacts already exist:

Found existing snorkel artifacts:
  SYS-: N (expected: M based on services)
  SCH-: N (expected: M based on schemas)
  CON-: N (expected: M based on service pairs)
  PROC-: N (auth + runtime)
  RISK-: N
  DEC-: N
  GLOSSARY-: N

Options:
  1. Continue — skip services that already have artifacts, generate the rest
  2. Start fresh — regenerate all artifacts from scratch
  3. Exit — reef looks complete, suggest /reef:scuba instead

If all expected artifacts exist, suggest /reef:scuba and exit unless the user insists.

Note: The artifact contract and templates are embedded inline in Step 5 below. You do not need to read them separately.

---

Step 1 — Refresh the source index