@haaaiawd/anws 2.3.0 → 2.4.1

package/templates_en/.agents/skills/runtime-inspector/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: runtime-inspector
+description: Load when `/probe` needs to identify runtime entrypoints, process boundaries, spawn chains, IPC channels, protocol strength, and lifecycle risks. Observes and reports only; does not modify code.
+---
+
+# Runtime Inspector (ALPHA)
+
+<phase_context>
+You are **RUNTIME INSPECTOR**.
+
+**Mission**: identify how the project starts, spawns processes, communicates, and fails; provide evidence for `/probe` Runtime Topology and Risk Matrix.  
+**Capabilities**: entrypoint discovery, spawn/fork chain detection, IPC surface inventory, protocol-strength classification, lifecycle and platform-security risk labeling.  
+**Limits**: do not start long-running services, do not modify code, and do not present static inference as runtime proof; use `Cannot confirm` when evidence is insufficient.  
+**Output Goal**: Process Roots, Spawning Chains, IPC Surfaces, Contract Status, Lifecycle Risks, and Security Flags.
+</phase_context>
+
+---
+
+## CRITICAL Output Contract
+
+> [!IMPORTANT]
+> Persisted-report rules, evidence rules, single-writer rules, and de-duplication rules follow `.agents/skills/output-contract/SKILL.md`. This skill returns an evidence slice for `/probe`.
+>
+> - Strong conclusions require a path, keyword, or command-output anchor.
+> - Runtime behavior that was not actually exercised must be phrased as static evidence or `Cannot confirm`.
+> - IPC contract classification must state the evidence: channel, message schema, version handshake, or missing pieces.
+> - Windows Named Pipe permissions and parent/child process lifecycle are priority checks.
+
+---
+
+## sequential-thinking Rules
+
+- No CoT model: call the `sequential-thinking` CLI.
+- CoT model + simple single-process project: natural CoT is acceptable, but still answer entrypoint, communication, and failure questions.
+- CoT model + multiprocess, IPC, spawn/fork, or protocol inference: call the `sequential-thinking` CLI.
+
+---
+
+## Step 1: Identify Entrypoints
+
+### What
+Search for entrypoints that may represent independent processes:
+
+| Language / Platform | Search Signals |
+| --- | --- |
+| Rust | `fn main()`, `#[tokio::main]` |
+| Python | `if __name__ == "__main__":` |
+| Node | `require.main === module`, `package.json` `bin` |
+| Go | `func main()` |
+
+### Why
+Entrypoints define process boundaries; multiple entrypoints usually imply deployment, IPC, or lifecycle risks.
+
+### Acceptance
+- Output `Process Roots`: path, entrypoint type, inferred role.
+- For multiple entrypoints, label independent process / parent-managed / `Cannot confirm`.
+
+---
+
+## Step 2: Trace Spawn Chains
+
+### What
+Search for parent processes launching children:
+
+| Platform | Search Signals |
+| --- | --- |
+| Rust | `Command::new`, `std::process::Stdio`, `tauri-plugin-shell` |
+| Python | `subprocess.Popen`, `multiprocessing.Process` |
+| Node | `child_process.spawn`, `child_process.fork` |
+
+### Why
+Spawn chains create lifecycle risk: parent exit, child crash, restart policy, and cleanup policy need explicit contracts.
+
+### Acceptance
+- Output `Spawning Chains`: parent path, child command/module, stdio/environment passing.
+- Label zombie child, silent failure, restart gap, and cleanup gap where visible.
+
+---
+
+## Step 3: Identify IPC Surfaces
+
+### What
+Search for communication channels and protocol definitions:
+
+| Category | Search Signals |
+| --- | --- |
+| Channel | `Pipe`, `NamedPipe`, `unix_stream`, `zmq`, `TcpListener`, `UdpSocket`, `websocket`, `http::server` |
+| Protocol | `Handshake`, `Version`, `MagicBytes`, `schema`, `protobuf`, `serde_json`, `JSON.parse`, `enum Message` |
+
+### Why
+A channel without schema, version, or handshake creates protocol drift, which is a core hidden risk in multiprocess systems.
+
+### Acceptance
+- Output `IPC Surfaces`: channel type, location, protocol evidence.
+- Every IPC surface has `Contract Status`.
+
+---
+
+## Contract Status
+
+| Status | Rule |
+| --- | --- |
+| Strong | channel + explicit message schema / enum / protobuf, or a version handshake |
+| Weak | channel + raw JSON/string, but no centralized schema or version |
+| None | channel exists, but no protocol definition is found |
+| Cannot confirm | static evidence is insufficient |
+
+---
+
+## Risk Patterns
+
+| Risk | Detection Signal | Recommendation |
+| --- | --- | --- |
+| Protocol Mismatch | channel exists without schema/version/handshake | add protocol schema or version handshake task |
+| Zombie Child | spawn exists without exit cleanup or heartbeat | add kill-on-exit, heartbeat, or cleanup contract |
+| Silent Failure | child failure has no error propagation or restart policy | add error propagation, retry, or supervisor strategy |
+| Named Pipe Permission Risk | Windows Named Pipe lacks explicit ACL | add permission-boundary design and verification |
+| Race Condition | multiprocess messages lack ordering, locks, or idempotency | add sequence numbers, locks, or idempotency contract |
+
+---
+
+## Required Output
+
+```markdown
+## Runtime Inspector Findings
+
+### Process Roots
+| Path | Entrypoint | Role | Confidence |
+
+### Spawning Chains
+| Parent | Child | Channel / stdio | Lifecycle Risk |
+
+### IPC Surfaces
+| Path | Channel | Protocol Evidence | Contract Status |
+
+### Lifecycle Risks
+| Risk | Evidence | Impact | Suggested follow-up |
+
+### Security Flags
+| Flag | Evidence | Severity | Suggested follow-up |
+```
+
+---
+
+<completion_criteria>
+- Process Roots, Spawning Chains, IPC Surfaces, Contract Status, and Lifecycle Risks are present or explicitly `N/A + reason`.
+- Strong/Weak/None/Cannot confirm classifications include evidence.
+- Static inference is not presented as runtime proof.
+- Output can be merged directly into `/probe` Runtime Topology and Risk Matrix.
+</completion_criteria>

package/templates_en/.agents/skills/sequential-thinking/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: sequential-thinking
+description: Use when complex problems require systematic step-by-step reasoning. Suitable for multi-stage analysis, design planning, problem decomposition, or tasks with unclear initial scope that require controlled convergence.
+---
+
+# Sequential Thinking
+
+The core of this skill is not "write more thoughts." It is to let AI **continuously advance, allow correction, and finally converge on conclusions** in complex problems. The CLI is only the execution carrier; the skill itself defines when to enter this thinking mode and how to avoid degrading sequential thinking into loose output.
+
+## Mission
+
+Use this skill to turn complex problems into a **bounded, correctable, reviewable reasoning process**:
+
+- Clarify the problem first, instead of rushing to answers
+- Allow correction and judgment updates during progress
+- Compare alternatives when complexity increases, instead of forcing one path
+- Converge to conclusions and recommendations within limited steps
+- Preserve a replayable reasoning trace at the end
+
+This skill does not solve "can't think." It solves "thinking too scattered, concluding too early, too hard to review."
+
+## Core Capabilities
+
+- **Iterative advancement**: break complex problems into consecutive steps
+- **Dynamic correction**: revisit and revise earlier judgments when new evidence appears
+- **Branch comparison**: compare alternatives before converging
+- **Context retention**: keep clear boundaries and goals in multi-step reasoning
+- **Conclusion closure**: must end with a judgment, not endless divergence
+
+## When to Use
+
+### Core Decision Rule
+
+> **Model capability sets baseline; task complexity decides escalation.**
+
+| Model capability | Simple task | Complex task |
+|---------|:-------:|:-------:|
+| **Has CoT** | Natural CoT is enough | Call ST CLI |
+| **No CoT** | **Must call ST CLI** | **Must call ST CLI** |
+
+### Mnemonic
+
+> **"No CoT -> must use ST**
+> **Has CoT -> use ST only for complex tasks"**
+
+### Scenarios where CLI is mandatory
+
+| Scenario | Decision standard | Why CLI is needed |
+|------|---------|---------------|
+| **No CoT model** | Current model cannot output chain-of-thought | External tool required to structure reasoning |
+| **Premise correction** | Earlier judgment is wrong and must be revised | CLI session keeps history for revision |
+| **Multi-option comparison** | Need trade-offs between 2+ candidates | `branch` mode is designed for this |
+| **Replayable trace** | Need auditable, reproducible reasoning | CLI can generate replay docs |
+| **Complex convergence** | Problem needs >5 steps to converge | Forced step limits prevent endless divergence |
+
+### Scenarios where natural CoT is enough (with CoT)
+
+| Scenario | Decision standard | Why CLI is not needed |
+|------|---------|-----------------|
+| **Linear reasoning** | No premise correction, linear progression | Model output is sufficient |
+| **Simple analysis** | Clear boundaries, <5 steps | No extra tooling required |
+| **Quick decision** | Need conclusion only, no replay trace | CoT is sufficient |
+| **Exploratory thinking** | Still diverging, uncertain about convergence | Explore with CoT first, then decide |
+
+### Decision tree
+
+```mermaid
+flowchart TD
+    A[Need multi-step reasoning?] -->|No| Z[Answer directly]
+    A -->|Yes| B{Model has CoT?}
+    B -->|No| CLI[Must call ST CLI]
+    B -->|Yes| C{Task complex?}
+    C -->|Simple: <5 steps, no revision| CoT[Natural CoT]
+    C -->|Complex: revision/comparison/replay| CLI
+```
+
+### Not suitable for
+
+- Simple fact lookup
+- Tasks solvable in one step
+- Problems with already obvious path and no multi-step derivation needed
+- Pure brainstorming without required convergence
+
+## Working Philosophy
+
+- **Find the core problem before answers**: do not mistake symptom description for root cause diagnosis
+- **Allow corrections instead of defending bad premises**: if earlier steps are wrong, go back and fix
+- **Reduce complexity before adding solutions**: identify the principal contradiction first
+- **Advance one step at a time**: current step states only current judgment
+- **Must land on conclusions**: "I can keep thinking" is not a default exit
+
+## Installation & Runtime Model
+
+This skill provides thinking method and invocation constraints for agents; CLI is distributed via npm.
+
+Before use, ensure CLI is installed locally:
+
+```bash
+npm install -g sequential-thinking-cli
+
+# or
+pnpm add -g sequential-thinking-cli
+```
+
+After installation, use `sthink` as command entry.
+
+## CLI Contract
+
+This skill no longer requires AI to hand-write thought JSON. Execution uses main CLI actions:
+
+- `start`
+- `step`
+- `replay`
+
+### `start`
+
+Accepts only four inputs:
+
+- `name`
+- `goal`
+- `mode`
+- `totalSteps`
+
+Constraints:
+
+- `mode` only allows `explore`, `branch`, `audit`
+- `totalSteps` only allows `5` or `8`
+
+If unsure which mode to use, default to `explore`. Use `branch` only when clearly comparing candidate paths; use `audit` only when clearly reviewing existing judgments.
+
+### `step`
+
+Accepts only:
+
+- `content`
+
+All other context should be automatically restored and injected by runtime.
+
+### `replay`
+
+Used to read completed sessions and generate replay docs; optionally export to current directory.
+
+## Recommended Workflow
+
+```text
+1. Decide whether the problem truly needs sequential-thinking; do not apply by default.
+2. If needed, install or confirm local npm CLI.
+3. Use `sthink start` with `name`, `goal`, `mode`, `totalSteps`.
+4. Use `sthink step` to advance step by step; each step contains only current progress.
+5. When new evidence appears, correct earlier judgments.
+6. At convergence, output conclusion, risks, and next-step recommendations.
+7. Optionally run `sthink replay` to generate/export replay docs.
+```
+
+## Examples
+
+The following examples are not for hand-writing JSON; they show where this skill provides real value: **advance, correct, converge**.
+
+### Example 1: Basic reasoning
+
+```bash
+sthink start --name "query-diagnosis" --goal "locate root cause of query performance degradation" --mode explore --totalSteps 5
+sthink step --sessionPath "<session-path>" --content "Do not rush to pick optimization means. First split layers: single SQL degradation, interface-level N+1, or upper-layer amplification. If root cause is unclear, cache/index/rewrite may all become patches."
+sthink step --sessionPath "<session-path>" --content "Logs show user-detail endpoint triggers many repeated reads in one request, with clear N+1 signals. But cannot conclude yet; repeated queries may be symptoms. Need to verify whether slowness is from query count or one inherently slow query. Increase total steps."
+sthink step --sessionPath "<session-path>" --content "Converged: primary cause is N+1 during list-page batch loading; secondary cause is missing index on related fields amplifying single-query cost. Sequence should remove N+1 first, then add index and validate tail latency."
+```
+
+### Example 2: Premise correction
+
+```bash
+sthink step --sessionPath "<session-path>" --content "After reviewing profiling results, prior judgment needs correction: the real bottleneck is missing index on join columns, which amplifies full-scan costs per join. N+1 still exists but is not first-order bottleneck; priority should move down."
+```
+
+### Example 3: Complex change decomposition
+
+```bash
+sthink start --name "change-impact-analysis" --goal "decompose impact and priorities of complex changes" --mode explore --totalSteps 5
+sthink step --sessionPath "<session-path>" --content "User proposed multiple rule changes at once; do not treat them as one type. Split by type: mechanism principles, numeric balancing, interface semantic changes, and doc-implementation drift."
+sthink step --sessionPath "<session-path>" --content "Build an impact matrix. Mechanism changes flow into ADR/System Design; numeric balancing affects rule tables/config/test baselines; interface semantic changes are most dangerous because they silently break caller assumptions."
+sthink step --sessionPath "<session-path>" --content "Converged: first handle items changing system boundaries or call semantics, then numeric/experience items. Sequence should fix docs/contracts before balancing, otherwise implementation and review build on drifting premises."
+```
+
+### Example 4: Branch comparison
+
+```bash
+sthink start --name "performance-tradeoff" --goal "compare priority of cache stopgap vs query optimization" --mode branch --totalSteps 5
+sthink step --sessionPath "<session-path>" --content "Option A: introduce cache first to reduce peaks. Fast effect, low interface intrusion, good for stopgap; downside is complexity in consistency/invalidation and may preserve accidental complexity. Option B: optimize indexes and rewrite queries directly. Root-cause oriented and cleaner long-term, but requires careful validation of write amplification, lock contention, and regression risk."
+```
+
+## Storage & Export Boundary
+
+- runtime automatically saves session state and step records
+- replay docs can be generated after completion
+- `replay` supports export to current directory for review/reuse
+
+## Heuristic Reminders
+
+These are heuristic prompts, not hard constraints. The key is reducing wasted loops and approaching conclusions.
+
+- **Problem-definition prompt**: Are you describing symptoms or locating root cause?
+- **Evidence prompt**: Is current judgment based on facts/observations or guesses?
+- **Boundary prompt**: Is impact local module, single system, or cross-system?
+- **Complexity prompt**: Are you reducing essential complexity or adding accidental complexity?
+- **Convergence prompt**: Is there enough to conclude, or still ineffective divergence?
+
+## Tips
+
+- Do not hand-write thought JSON; let CLI runtime handle pacing, persistence, replay
+- Do not treat sequential-thinking as default; use only when multi-step convergence is truly needed
+- If unsure mode, start with `explore`
+- `step` `content` should only express current progress, not repeated full context
+- If a premise is wrong, state correction explicitly
+- At convergence, clearly output conclusions, risks, next actions
+- `replay` is available only for completed sessions

package/templates_en/.agents/skills/spec-writer/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: spec-writer
+description: "genesis Step 2: turn fuzzy or high-level needs into strict product requirement documents (PRDs); includes craft scaffolding, PRD spec contract, optional sub-agent shard orchestration, and Step completion signals. Use when requirements are vague, scope is too large, or expression stays conceptual."
+---
+
+# Requirements Detective Handbook
+
+> "The hardest part of building software isn't how to implement it—it's precisely defining what to implement."
+
+Your job is to **eliminate ambiguity**.
+
+## genesis Step 2 (scope and handoff)
+
+Compared with `templates/.agents/skills/spec-writer`, this template adds **craft scaffolding**, **spec contract** (on-disk semantics), **sub-agent orchestration**, and **completion**. The normative force of **Execution checklist / Methodology / 10-dimension ambiguity scan / User Story quality gate** sections is **unchanged**—rules such as Socratic probing, **one question at a time**, the hard cap on `[NEEDS CLARIFICATION]`, Non-Goals, and the User Story gate **apply verbatim**.
+
+### Craft scaffolding (artifact skeleton)
+
+Before **Execution checklist** step 4 (writing `01_PRD.md`), the skeleton **must first** be in place; when filling content, **do not remove normative sections** from the template. Where there is no information, write **`[NOT APPLICABLE | reason]`** or **`[ASSUMPTION]`**—never leave blanks that pretend completeness.
+
+| Artifact | Path | Requirement |
+|----------|------|---------------|
+| Version directory | `.anws/v{N}/` | `v{N}` must match host genesis / session convention; create on first round or explicitly reuse existing `v{N}`; silent fork forbidden. |
+| PRD | `.anws/v{N}/01_PRD.md` | **Single source of truth** for Step 2 output; content driven by `references/prd_template.md`; **forbidden** to replace on-disk artifact with long chat-only prose only. |
+| Template | `references/prd_template.md` | Read in full **before** drafting PRD; heading levels and mandatory sections follow the template; extra appendices allowed but cannot replace mandatory template sections. |
+
+**Readiness check (internal; may summarize for user):** `v{N}` chosen; this SKILL + `prd_template.md` read; enumerate at least 3 User Story drafts and ≥3 Non-Goals before expanding written PRD sections.
+
+### Spec contract (PRD on-disk semantics)
+
+> [!IMPORTANT]
+> When folded into the genesis pipeline, PRD sections are treated as **assertable draft contracts** for downstream work (architecture, task breakdown, challenge) and must satisfy:
+>
+> - **Verifiable:** Any statement of "must / must not / SLA / user counts / compatibility" needs Given-When-Then, metrics, or enumerated options; otherwise it cannot be marked as implemented—only `[ASSUMPTION]` or move to Non-Goals.  
+> - **Traceable:** Every User Story carries `[REQ-XXX]`; terms and systems must be **internally consistent** with "Affected systems" below (when aligning to `02_ARCHITECTURE_OVERVIEW.md` downstream, no arbitrary renames).  
+> - **Ambiguity-bounded:** `[NEEDS CLARIFICATION]` **≤ 3** (hard limit); if exceeded, use defaults + `[ASSUMPTION: …]`; **forbidden** to re-ask generic defaults stated in this document's 10-dimension scan to pad counts.  
+> - **Value-traceable:** Every requirement aligns to user value in one sentence; Non-Goals and Goals are **mutually exclusive** with no empty "maybe won't do".  
+> - **Consistent:** The same fact is **not stated twice contradictorily** in summary vs detail; fixes use **atomic paragraph replacement**, not side-by-side conflicting wording.
+
+Challenge / downstream alignment: If excerpts from the PRD appear in reports or attachments, excerpts must carry **subsection anchors** or **stable headings from `01_PRD.md`**; do not cite only "see PRD".
+
+### Sub-agent orchestration (optional)
+
+When the host supports parallel sub-sessions:
+
+| Role | Responsibility |
+|------|----------------|
+| **Parent agent** | Choose `v{N}`, load user intent and context, merge structured blocks returned by sub-agents, **dedupe and pick best among same-topic answers**, maintain **single writer** for `.anws/v{N}/01_PRD.md`, run mandatory "10-dimension ambiguity scan" and User Story quality gate, then deliver for user confirmation. |
+| **Sub-agent** | Consumes bounded slices only—e.g. "generate clarification question batches only (with suggested answers)", "extract / rewrite User Stories only (still drafts)", "annotate dimension k of the 10-dimension table with Clear/Partial/Missing + patch suggestions", "rewrite feeling words into candidate metric lists only"; return **Markdown structured blocks + anchor suggestions**; do not assume access to parent-only context. |
+
+**Single writer:** Only **one** writer for `01_PRD.md` per genesis Step 2 round; sub-agents must not write that path without parent authorization.
+
+#### Handoff checklist (sub → parent)
+
+- [ ] State deliverable type (question list / Story draft / scan vector / feeling-word metric table) and **N/A dimensions** (one-line reason each).
+- [ ] Every item maps to a **subsection title or `[REQ-XXX]` placeholder** the PRD will use; if no anchor, mark "pending parent mount".
+- [ ] Do not introduce requirements conflicting with parent-declared Non-Goals; if conflict is possible, list "requires parent ruling".
+- [ ] Sub-agent stops at structured handoff; subsequent edits merged by parent.
+
+### Completion (genesis Step 2 done signal)
+
+Step 2 **must not be claimed complete** unless all of:
+
+| Gate | Condition |
+|------|-----------|
+| On-disk | `.anws/v{N}/01_PRD.md` exists and opens standalone; structure aligns with **mandatory sections** of `prd_template.md`. |
+| Content | Contains User Stories (pass quality gate), acceptance criteria, **≥3** Non-Goals; every requirement is testable, measurable, or explicitly assumed. |
+| Ambiguity | "10-dimension ambiguity scan" executed; every `Partial` / `Missing` fixed, `[ASSUMPTION]`-ized, or closed under hard-limit rules. |
+| Tags | `[NEEDS CLARIFICATION]` **≤ 3**; no Story has untracked feeling words unless rewritten or assumed away. |
+| Human | **User confirmed PRD** (or explicitly waived in writing logged as `[ASSUMPTION: stakeholder sign-off deferred]`); do not fake confirmation. |
+| Handoff | Parent delivered **short summary table** to user (goals / key REQ count / open clarifications / Non-Goals count / recommended reading order for next Step). |
+
+Failing any **hard** row above → Step 2 is **blocked / in_progress**; do not silently advance the pipeline into architecture drafting.
+
+---
+
+## Execution checklist (single source of order)
+
+Aligned with **craft scaffolding** and the **completion** table above; release is gated by **completion hard rows**—this section only sequences work (merges former Quick start / Mandatory steps / Completion checklist to avoid duplicate reading).
+
+1. **Read the request**: identify feeling words and hidden boundaries (mandatory).
+2. **Think deeply**: 3–7 rounds of structured reasoning (by complexity); produce User Story drafts, ambiguity, clarification questions (mandatory).
+3. **Probe for answers**: do not advance the main line until answers arrive (mandatory).
+4. **Before disk**: ≥3 User Stories, ≥3 Non-Goals, clarify feeling words; read `references/prd_template.md`, create `.anws/v{N}/01_PRD.md`—**do not** substitute chat for disk (mandatory).
+5. **After disk**: run the **10-dimension ambiguity scan** and close `Partial` / `Missing`; User Story quality gate; `[NEEDS CLARIFICATION]` ≤ 3 (mandatory).
+6. **Close**: satisfy **completion** hard rows + user sign-off on PRD (or logged waiver).
+
+## Methods and tools
+
+### 1. Socratic probing
+*   **User:** "I want it to be fast."
+*   **You:** "Does that mean p99 under 100ms? Or optimistic UI updates only?"
+*   *Goal:* Turn adjectives into numbers and verifiable criteria.
+
+### 2. Context compression
+*   **Input:** 500-line chat log.
+*   **Action:** Extract *User Stories*—"As a User, I want X, so that Y."
+*   **Drop:** Premature implementation details (e.g. "use Redis").
+
+### 3. Non-Goals (draw the circle)
+*   Explicitly define what we **do not do**.
+*   *Why:* Prevent scope creep and endless "what about X?" follow-ups.
+
+## Detective rules
+
+1.  **Contract first:** If it cannot be verified, do not put it in the PRD.
+2.  **Don't steal design work:** Describe *what* to do, not prematurely *how*. Implementation belongs in architecture.
+3.  **User value first:** Every requirement must trace to clear user value.
+
+## Toolbox
+*   `references/prd_template.md`: Product requirements template.
+
+## 10-dimension ambiguity scan
+
+After drafting the PRD, you **must** scan the full text across these 10 dimensions. This replaces ad-hoc "anything else?" with a **repeatable, exhaustive** pass.
+
+For each dimension, mark status: `Clear` / `Partial` / `Missing`
+
+| # | Dimension | What to check | Status |
+|---|-----------|---------------|:------:|
+| 1 | **Functional scope and behavior** | Core goals / success criteria / explicit exclusions / user role distinction | |
+| 2 | **Domain and data model** | Entities, attributes, relationships / uniqueness rules / lifecycle and state transitions / data volume assumptions | |
+| 3 | **Interaction and UX flows** | Key user paths / error, empty, loading states / a11y and i18n | |
+| 4 | **Non-functional quality** | Performance / scalability / reliability / observability / security and privacy / compliance | |
+| 5 | **Integrations and externals** | External failure modes / import-export formats / protocol version assumptions | |
+| 6 | **Edge cases and failures** | Negative paths / rate limits / concurrent conflict handling | |
+| 7 | **Constraints and tradeoffs** | Technical constraints / explicit tradeoffs / rejected architecture options | |
+| 8 | **Terminology consistency** | Glossary / synonym unification across the doc | |
+| 9 | **Done signals** | Acceptance testable? / DoD quantifiable? | |
+| 10 | **Placeholders and vague words** | TODOs / unquantified adjectives (fast, scalable, secure, intuitive, robust) | |
+
+**Rules:**
+- For `Partial` or `Missing`, sort by **impact × uncertainty**, ask user about top **5**
+- **One question at a time**; offer a suggested answer; user may accept or customize
+- After answers, **atomically write** the matching PRD section; no mutually contradictory text
+- `[NEEDS CLARIFICATION]` **hard cap ≤ 3**; if still over, use reasonable defaults + `[ASSUMPTION: ...]`
+- **Do not ask users to clarify these reasonable defaults:** industry-standard data retention, typical web/mobile performance expectations, friendly errors with fallbacks, standard Session or OAuth2 authentication
+
+## User Story quality gate
+
+Every User Story in the PRD **must** pass before the PRD is considered done:
+
+| Check | Requirement |
+|-------|---------------|
+| **Unique ID** | Must include `[REQ-XXX]` for traceability |
+| **Priority** | P0 / P1 / P2, P0 first |
+| **Independently testable** | How the story is **independently** demoed and verified |
+| **Affected systems** | Concrete system IDs (must align with `02_ARCHITECTURE_OVERVIEW.md`) |
+| **Acceptance criteria** | At least one Given-When-Then + at least one error path |
+| **Edge cases** | At least one boundary condition |
+| **No vague feeling words** | No unquantified adjectives (e.g. fast → <100ms p99; scalable → supports N users) |
+| **User value** | One-sentence end-user value |
+
+If any User Story fails, **fix before delivering the PRD**.