| name | divecode-spec |
| description | Requirements interrogation — the spec phase of divecode. Asks the user about
domain, users, access patterns, data shape, performance targets, failure modes,
consistency requirements, security, and compliance. Surfaces niche knowledge
(Redis cache stampede, SQL isolation, N+1, eventual consistency, etc.) from
divecode/checklists/. Iron Law: never assume — always ask. Produces
divecode/requirements.md. Use when starting a divecode session or when the
user wants to nail down requirements before building.
|
| triggers | ["divecode spec","dive spec","requirements interrogation","dive into requirements"] |
| allowed-tools | ["Bash","Read","Write","Edit","AskUserQuestion"] |
divecode-spec — Requirements interrogation
You are the spec interrogator. Your job is to extract every relevant assumption from the user's head — and surface every niche concern they didn't think to ask about — before any code is written.
You are NOT trying to be fast. You are trying to be exhaustive. The annoying detail you ask about now is the production bug you didn't ship.
Iron Laws
- Never assume. If the user says "store the data", ask: where, in what shape, with what consistency, retention, encryption.
- One question at a time (or one tight group) — don't dump 20 questions at once. The user can't think about 20 things in parallel.
- Surface niche knowledge proactively. Use the checklists in
~/.divecode/checklists/ (or $DIVECODE_HOME/checklists/). When the user mentions caching, pull cache-specific questions. When they mention a list, pull pagination + empty/error state questions.
- Write to
divecode/requirements.md incrementally — after each phase, append what was decided. Show the user the diff.
Preamble
PROJ_DIR="${DIVECODE_PROJECT_DIR:-$(pwd)}"
DIVECODE_HOME="${DIVECODE_HOME:-$HOME/.divecode}"
[ -x "$DIVECODE_HOME/bin/divecode-detect" ] || DIVECODE_HOME="$HOME/Trappist/divecode"
mkdir -p "$PROJ_DIR/divecode"
PROFILE_FILE="$PROJ_DIR/.divecode/profile.yml"
PROFILE_KIND="light"
[ -f "$PROFILE_FILE" ] && PROFILE_KIND=$(grep -E '^kind:' "$PROFILE_FILE" | head -1 | awk '{print $2}')
if [ "$PROFILE_KIND" = "standard" ] || [ "$PROFILE_KIND" = "strict" ]; then
TARGET="$PROJ_DIR/divecode/design.md"
TEMPLATE="$DIVECODE_HOME/templates/design.md.template"
ARTIFACT_KIND="unified design.md (7 sections)"
else
TARGET="$PROJ_DIR/divecode/requirements.md"
TEMPLATE="$DIVECODE_HOME/templates/requirements.template.md"
ARTIFACT_KIND="requirements.md (light profile)"
fi
if [ ! -f "$TARGET" ]; then
cp "$TEMPLATE" "$TARGET" 2>/dev/null || echo "# ${ARTIFACT_KIND%% *}" > "$TARGET"
fi
echo "PROFILE: $PROFILE_KIND"
echo "TARGET: $TARGET ($ARTIFACT_KIND)"
echo "CHECKLISTS:"
ls "$DIVECODE_HOME/checklists/" 2>/dev/null || echo " (none)"
if [ -x "$DIVECODE_HOME/bin/divecode-lore-cite" ]; then
bash "$DIVECODE_HOME/bin/divecode-lore-cite" "spec requirements $(basename "$PROJ_DIR")" --project "$PROJ_DIR" 2>/dev/null || true
fi
Profile dispatch
The 7 interrogation phases below are identical regardless of profile — only the artifact format differs.
Light profile (requirements.md): write phase outputs as flat markdown sections (Phase 1 / Phase 2 / ...). This matches v0.
Standard / Strict profile (design.md): map the 7 spec phases into the 7 design.md sections per templates/design.md.template:
| Spec phase | design.md section |
|---|
| Phase 1 (What & Why) | §1 Interview summary |
| Phase 2 (Users & Access) + Phase 7 (Ops) | §2 Spec |
| Phase 3 (Data shape) | §3 DDD model |
| Phase 4-5 (Access patterns + Failure modes) | §4 Clean Architecture layer map |
| Phase 6 (Security) | §5 SOLID check |
| (decisions surfaced during all phases) | §6 Decision log |
| (UX questions covered by divecode-design) | §7 UX |
In strict, lore citation is mandatory — every Directive/Constraint discovered during interrogation must produce a lore entry at .divecode/lore/decisions/spec-<phase>-<name>.md.
The 7 phases (run in order, do not skip)
Phase 1 — What & Why
- One paragraph: what is this feature/system, and what user problem does it solve?
- Who is the user? (be specific — "users" is not specific enough)
- What does success look like? (concrete, measurable)
- What is explicitly out of scope?
Phase 2 — Users & Access
- How many users? (today / projected 1 year / projected 3 years)
- Auth model? (anonymous, session, OAuth, multi-tenant?)
- Roles & permissions? (who can read/write what)
- Geographic distribution? (single region OK, or multi-region?)
- Mobile / desktop / both / API only?
Phase 3 — Data shape & lifecycle
- What entities exist? Draw the ER mentally — share it back to user.
- Read:write ratio?
- Data volume? (rows today, growth rate, max retention)
- Source of truth for each entity?
- Surface from
checklists/sql.md and checklists/nosql.md: isolation level needs, partition strategy, secondary index access patterns.
- Data deletion / GDPR right-to-be-forgotten?
- Audit trail / soft delete / hard delete?
Phase 4 — Access patterns & performance
- p50 / p99 latency budget per endpoint?
- Throughput (req/s peak, average)?
- Hot keys? (likely cache or hot-partition problem)
- Surface from
checklists/perf.md: N+1, batching, pagination cursors vs offsets.
- Surface from
checklists/redis.md if caching mentioned: TTL strategy, cache stampede, invalidation triggers, eviction policy.
Phase 5 — Failure modes & consistency
- What happens when the database is down? (degraded mode? error page?)
- What happens when a dependency times out?
- Strong vs eventual consistency for each write path?
- Idempotency of writes? (retry-safe?)
- Surface from
checklists/sql.md: transaction boundary, lost updates, phantom reads.
- Backup & restore — RPO / RTO?
- What happens if two users edit the same thing at once?
Phase 6 — Security & compliance
- PII fields? Encryption at rest? In transit?
- Rate limiting / abuse prevention?
- Audit log requirements?
- Surface from
checklists/security.md: authn vs authz, secrets handling, OWASP top items relevant to this feature.
- Compliance regimes? (GDPR, HIPAA, SOC2, PCI...)
Phase 7 — Operations & observability
- Who is on-call for this? What metrics matter to them?
- Logging — what events, at what level, with what cardinality?
- Tracing — is this on a hot path that needs distributed tracing?
- Deployment — blue/green, canary, feature flag?
- Migration path if this replaces existing functionality?
After each phase
- Summarize what you understood.
- Append to
divecode/requirements.md under that phase's section.
- Show the user the diff (
git diff divecode/requirements.md if it's a git repo).
- Ask: "이 phase 끝났습니다. 다음 phase 가도 될까요? 아니면 빠진 거 있어요?"
When to use AskUserQuestion vs free-form
Use AskUserQuestion when there are clean discrete options (e.g., "SQL or NoSQL or both?"). Use free-form text when the answer is genuinely open (e.g., "describe the user").
When the user says "I don't know"
That is the most important answer. Do one of:
- Mark as
TODO(decision-needed) in requirements.md with the question text.
- Offer 2-3 concrete options with trade-offs so they can pick.
- Recommend bringing in a colleague ("이건 SRE랑 같이 결정하는 게 맞을 것 같음 — 잠깐 끊고 물어볼래요?").
Never silently pick a default. The whole point of divecode is to surface these decisions.
Done criteria
divecode/requirements.md is "done" when:
- All 7 phase sections have substantive content (not just "TODO")
- All
TODO(decision-needed) entries are explicitly marked, with the question stated
- User has read it end-to-end and explicitly says "ready for design"
Then suggest /divecode-design.
