interaction-doc · Interactive Product Documentation

English | 中文

Turn vague requirements into production-ready product documentation — interactive generation · closed-loop guarantees · ready to use out of the box

interaction-doc is a Claude Code skill that takes fuzzy product requests, one-line feature ideas, or a full PRD, clarifies them through multi-round interactive Q&A, and produces a usable, closed-loop, implementable interaction document (交互文档.md) — a spec that frontend, backend, and QA engineers can build from directly.

Distilled from real enterprise-grade project experience (a DAM digital asset management phase-1 project: 20 chapters / 1,700+ lines of interaction documentation).

---

Why

Product requirements are rarely clear upfront. Writing the document directly is a common source of:

• Undefined terms (e.g. an "asset owner" that nobody ever defined)
• State-machine deadlocks (e.g. an empty sub-category can't be deleted, but there's no other way to clean it up)
• Orphan references ("see 11/18" when the real section is 11/19)
• Missing definitions: entry points without defined functionality, permission matrices that contradict page-level descriptions

These issues surface during development and are extremely expensive to fix. interaction-doc eliminates them at the documentation stage through three layers: interactive questioning, conflict detection, and closed-loop checking.

Works wonders on vague requirements: the requirement is two sentences? No problem — the skill asks step by step (business goals → roles & permissions → entity state machines → flows → field-level validation) and writes the document as the answers come in.

Holds irresponsible PMs accountable: every unconfirmed rule is explicitly marked "to be confirmed" and tracked in an open-issues appendix. The skill never invents rules on the user's behalf.

---

Features

Feature	Description
Interactive clarification	Multi-round Q&A from high-level to low-level (via AskUserQuestion), with conflict detection after every round; unresolved questions are never silently decided
Production-ready output	Every feature spec includes: entry points, steps, validation rules (with boundary values), post-conditions, permissions, empty/error states, and copy — vague docs can't be built from
Closed-loop guarantees	Pre-delivery checklist: no state-machine deadlocks, no orphan cross-references, permission matrix consistent with page visibility, every entry point has a complete flow
Requirement coverage audit	Before delivery, every input requirement is mapped to its document section in a coverage table (requirement → source → section → status) for full traceability
Key API contracts	Core business modules include an interface table (name / method / path / key params / returns / permissions) so frontend and backend align directly
Versioning	Version headers plus a revision-history appendix for clean iteration tracking
Distilled from enterprise experience	Built on a real DAM project retrospective: question-round transcripts, deadlock cases, and cross-check misses (see references/dam_case.md)

---

Installation

Option 1: Plugin Marketplace (recommended, auto-updates)

/plugin marketplace add weigre/interaction-doc
/plugin install interaction-doc@interaction-doc

Option 2: Manual install

git clone https://github.com/weigre/interaction-doc.git
cp -r interaction-doc/plugins/interaction-doc/skills/interaction-doc ~/.claude/skills/

Option 3: .skill package

Download dist/interaction-doc.skill and extract it to ~/.claude/skills/interaction-doc/.

---

Usage

Just state your requirement, for example:

• "Produce an interaction document from this PRD" (you can attach the PRD file)
• "I want to build an in-house design asset management system, frontend and backend"
• "Revise this legacy interaction document into a closed-loop, deliverable spec"
• "Walk me through the flow of this feature"

---

Workflow

Phase 0    Understand input      → fuzzy request / full PRD / legacy-doc iteration; build a fact list
Phase 1    Q&A loop              → high-level (goals/roles/state machines) → low-level (fields/validation/copy);
                                   conflict checks every round; confirmed decisions are written into the doc immediately
Phase 2    Build document        → organize by page + per-page layout sketch + key API contract tables
Phase 3    Closed-loop check     → references / permissions / state machine / flows / errors / empty states / terms / numeric consistency
Phase 3.5  Requirement audit     → map every input requirement to its section
Phase 4    Deliver               → 交互文档.md (with version, coverage table, revision history, appendix)

---

Quality

During development, 4 scenario groups were evaluated with/without the skill (fuzzy request / full PRD / contradictory-doc iteration / enterprise DAM PRD) and iterated until stable:

• With skill: 30/30 assertions pass (permission matrix, state machine, validation rules, interface lists, requirement coverage table, orphan references, etc.)
• The no-skill baseline shows clear gaps on key assertions such as interface lists and coverage audits

---

Repository layout

interaction-doc/
├── marketplace.json              # Plugin marketplace manifest
├── plugins/interaction-doc/
│   ├── .claude-plugin/plugin.json
│   └── skills/interaction-doc/
│       ├── SKILL.md              # Core workflow (Phase 0-4 + closed-loop checklist)
│       └── references/
│           ├── doc_structure.md  # Recommended section-structure template
│           └── dam_case.md       # Enterprise case retrospective (real-world reference)
└── dist/
    └── interaction-doc.skill     # Packaged .skill file

---

License

MIT License