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

| Command | Purpose | | --------------- | ----------------------------- | | openq next-id | Generate next QID for a flow | | openq append | Append question entry to file |

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

stdout: QID string for both next-id and append (append returns the assigned QID)
exit code: 0 on success, non-zero on failure
File missing: next-id returns first ID (e.g., OQ-SIG-001); append creates file with header if needed
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

| Field | Description | Example | | ------------------ | ----------------------------------------------- | ---------------------------- | | - A: | The answer/decision made | JWT approach adopted | | Resolved in: | Artifact where resolution is documented | requirements.md (REQ-003) | | Resolution SHA: | Git commit where resolution occurred | abc123def or null | | Validated by: | Agent/critic that validated the resolution | requirements_critique |

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

| Status | Marker | Meaning | | ------------ | ------------ | ---------------------------------------------- | | Open | [OPEN] | Question awaiting resolution | | Resolved | [RESOLVED] | Question answered with evidence | | Deferred | [DEFERRED] | Valid question, not needed for current flow |

Resolution Criteria

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

Explicit answer: The question has a - A: line with an answer
Status change: Question text changed from [OPEN] to [RESOLVED]
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:

Just call append — it auto-generates and returns the QID
Never hand-roll QID counters — let the tool handle sequencing
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

| Flow | Code | Example QID | | ------ | ------ | ------------- | | signal | SIG | OQ-SIG-001 | | plan | PLAN | OQ-PLAN-001 | | build | BUILD | OQ-BUILD-001 | | review | REVIEW | OQ-REVIEW-001 | | gate | GATE | OQ-GATE-001 | | deploy | DEPLOY | OQ-DEPLOY-001 | | wisdom | WISDOM | OQ-WISDOM-001 |

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:

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