Open Questions Tools Skill

Helpers for the open questions register (open_questions.md). Generates sequential QIDs and appends entries.

Invocation

Always invoke via the shim:

bash .claude/scripts/demoswarm.sh openq <command> [options]

Do not set PATH or call helpers directly. The shim handles resolution.

Operating Invariants

Repo root only

• Assume working directory is repo root.
• All paths are repo-root-relative.

QID format

• Pattern: OQ-<FLOW>-<NNN> (e.g., OQ-SIG-001, OQ-PLAN-002, OQ-BUILD-003)
• Flow codes: SIG (signal), PLAN (plan), BUILD (build), REVIEW (review), GATE (gate), DEPLOY (deploy), WISDOM (wisdom)
• Sequential within flow (auto-incremented from existing entries)

Append-only

• Never modifies existing entries
• Only appends new questions at the end

Allowed Users

Primary:

• clarifier
• Flow orchestrators (when questions arise mid-flow)

Secondary:

• Any agent that needs to register an open question rather than guessing

Command Reference

Quick Examples

Generate next QID

# Get next available QID for signal flow
bash .claude/scripts/demoswarm.sh openq next-id \
  --file ".runs/feat-auth/signal/open_questions.md" \
  --prefix "SIG"
# stdout: OQ-SIG-003 (next available)

# For plan flow
bash .claude/scripts/demoswarm.sh openq next-id \
  --file ".runs/feat-auth/plan/open_questions.md" \
  --prefix "PLAN"
# stdout: OQ-PLAN-001 (if empty)

Append a question

# Append new open question (auto-generates QID)
bash .claude/scripts/demoswarm.sh openq append \
  --file ".runs/feat-auth/signal/open_questions.md" \
  --prefix "SIG" \
  --question "Should authentication use JWT or session cookies?" \
  --default "Use JWT for stateless authentication" \
  --impact "Session cookies require server-side state management"
# stdout: OQ-SIG-003 (the assigned QID)

Contract Rules

1. stdout: QID string for both next-id and append (append returns the assigned QID)
2. exit code: 0 on success, non-zero on failure
3. File missing: next-id returns first ID (e.g., OQ-SIG-001); append creates file with header if needed
4. Auto-increment: append automatically generates the next QID (no need to call next-id first)

Entry Format

Appended entries follow this format:

- QID: OQ-SIG-003
  - Q: Should authentication use JWT or session cookies? [OPEN]
  - Suggested default: Use JWT for stateless authentication
  - Impact if different: Session cookies require server-side state management
  - Added: 2025-12-12T10:30:00Z

Resolution Format

When a question is resolved, the original entry is updated (status changed) and resolution fields are appended. Resolution tracking enables cleanup agents to count resolved vs unresolved questions.

Resolution Fields

Resolved Entry Example

- QID: OQ-SIG-001
  - Q: Should authentication use JWT or session cookies? [RESOLVED]
  - Suggested default: Use JWT for stateless authentication
  - Impact if different: Session cookies require server-side state management
  - Added: 2025-12-12T10:30:00Z
  - A: JWT approach adopted per security requirements
  - Resolved in: requirements.md (REQ-003)
  - Resolution SHA: abc123def
  - Validated by: requirements_critique

Status Values

Resolution Criteria

A question is considered resolved when any of these conditions are met:

1. Explicit answer: The question has a - A: line with an answer
2. Status change: Question text changed from [OPEN] to [RESOLVED]
3. Requirement linkage: A requirement explicitly addresses the question (QID referenced in requirements.md)

Counting Resolutions

Cleanup agents use these patterns for mechanical counting:

# Count total questions
bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/<run-id>/signal/open_questions.md" \
  --regex '^- QID: OQ-[A-Z]+-[0-9]{3}' \
  --null-if-missing

# Count resolved questions (with - A: lines)
bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/<run-id>/signal/open_questions.md" \
  --regex '^- A:' \
  --null-if-missing

# Count questions with [RESOLVED] status
bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/<run-id>/signal/open_questions.md" \
  --regex '\[RESOLVED\]' \
  --null-if-missing

Note: Resolution count may differ from - A: count if questions are resolved via requirement linkage rather than explicit answers.

For Agent Authors

In clarifier or when questions arise:

1. Just call append — it auto-generates and returns the QID
2. Never hand-roll QID counters — let the tool handle sequencing
3. Use next-id only if you need to preview the ID before appending

Example pattern:

# Simple: append directly (auto-generates QID, returns it)
QID=$(bash .claude/scripts/demoswarm.sh openq append \
  --file ".runs/${RUN_ID}/signal/open_questions.md" \
  --prefix "SIG" \
  --question "What is the expected session timeout?" \
  --default "30 minutes of inactivity" \
  --impact "Shorter timeout improves security but reduces UX")

echo "Registered question: $QID"

Flow Codes Reference

Installation

The Rust implementation is preferred. Install to repo-local directory:

cargo install --path tools/demoswarm-runs-tools --root .demoswarm

The shim will automatically resolve in order:

1. .demoswarm/bin/demoswarm (repo-local install, preferred)
2. demoswarm on PATH (global install)
3. cargo run fallback (dev environments)
4. Python fallback (legacy)