# Openq Tools

> Open questions register. Use for: QID generation, OQ-SIG-001 format IDs, append questions, open_questions.md. Generate sequential QIDs, append questions with context. Use in clarifier when registering open questions instead of guessing. Invoke via bash .claude/scripts/demoswarm.sh openq next-id|append.

- Skill: `majiayu000/openq-tools` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/openq-tools`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/openq-tools/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/openq-tools

---


# 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
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

```bash
# 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

```bash
# 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:

```markdown
- 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

```markdown
- 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:

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:

```bash
# 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:

```bash
# 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:

```bash
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)