--- name: openspec-change-interviewer-8400fbc20270 description: Interview the user to clarify and complete an OpenSpec change package under openspec/changes/CHANGE_ID/ by reading existing proposal/design/tasks and specs files, asking high-information-gain questions (no assumptions), then writing the refined content back into those files and validating with openspec validate CHANGE_ID --strict. --- # OpenSpec Change Interviewer (Instruction-Only) Follow these instructions when this skill is invoked to refine and complete an OpenSpec change directory. The output MUST be persisted as edits inside `openspec/changes//` (not only in chat). ## Invocation - Preferred: `$openspec-change-interviewer ` - If `` is missing, ask the user for it once, then proceed. ## Non-negotiables - Do not “fill in” requirements/design/AC by guessing. Ask questions; record unresolved items as open questions. - Merge rather than rewrite: preserve existing author content and structure whenever possible. - If restructuring is necessary, keep original text under an appendix section in the same file (so reviewers can diff intent). - Never record unconfirmed information as fact. Use `Assumption:` / `Open Question:` labels. ## Phase A — Read & Diagnose (before interviewing) 1. Resolve the change directory - `change_dir = openspec/changes//` - If missing, stop and ask whether to create scaffolding (do not create without confirmation). 2. Inventory and read (this order) - `tasks.md` (or `task.md` if present instead) - `proposal.md` (if present) - `design.md` (if present) - `specs/` directory (if present): read all `*.md`/`*.txt` spec files (start with the smallest/highest-level file first if there are many). 3. Build a concise “gap list” to drive questions Focus on missing or ambiguous items that would block implementation/review: - Goal/success criteria unclear or unmeasurable - In-scope vs out-of-scope not explicit (MVP boundary) - Primary flows/journeys incomplete (including failure paths, retries, rollback) - Interfaces undefined (API/event shapes, auth, versioning, error codes) - Data model unclear (entities/fields, lifecycle, constraints, migrations) - Architecture decisions missing (partitioning, dependencies, trade-offs) - Non-functional requirements missing (perf, reliability, security, privacy) - Acceptance criteria not executable (no clear “how to verify”) - Operational concerns missing (observability, alerts, runbooks) Do not start writing “final” text yet—only prepare the questions. ## Phase B — Interview (multi-round, high-information-gain) Ask questions in rounds (no fixed per-round limit). Decide how many to ask per round dynamically based on the remaining gaps and the user’s responsiveness. Start broad, then drill down. Keep each question concise and prioritize by information gain. If the user says `先这样` or `按目前信息写回`, stop asking and proceed to Phase C with remaining items recorded as open questions. When listing questions, use a Markdown ordered list and rely on auto-numbering (write `1.` for every item) to avoid numbering gaps. ### Order of inquiry 1. Goals and success - Who benefits? What pain is solved? - What measurable outcome indicates success? - What constraints are non-negotiable (timeline, compatibility, compliance)? 2. Scope boundaries - In-scope vs out-of-scope (explicit) - MVP vs follow-ups/roadmap - Backward compatibility expectations 3. Key flows - Happy path step-by-step - Failure/timeout paths and user-visible behavior - Idempotency, retries, rollback, and partial failure handling 4. Data and interfaces - Entities and fields (required/optional), validation rules - APIs/events: request/response, authz/authn, versioning, error codes - Data ownership and source-of-truth 5. Architecture and trade-offs - Where does the logic live (modules/services)? - Alternatives considered and why rejected - Performance, consistency, caching, and scaling assumptions 6. Risks and acceptance - Risk register + mitigations - Test strategy (unit/integration/e2e/manual) + runnable commands where possible - Executable acceptance criteria ### Branching triggers (ask immediately when mentioned) - Multi-tenancy → isolation model, tenant identifiers, cross-tenant access controls, migrations - Offline/background sync → conflict resolution, retry/backoff, state reconciliation - Security/privacy/GDPR → data retention, audit logs, encryption, PII handling - UI/UX → empty/loading/error states, permission-denied copy, a11y/i18n needs ## Phase C — Write-back (persist into the change directory) Write updates into existing files; create new files only if there is no natural home. Prefer ASCII kebab-case filenames for new specs (e.g., `api.md`, `data-model.md`, `migration.md`, `acceptance.md`, `ux.md`). ### `tasks.md` (or `task.md`) - Ensure tasks are actionable and sequenced. - For each task, include acceptance and test details (either inline or as a short sub-block) so completion is verifiable. - Preserve any existing task conventions (e.g., `[#R12]` refs) rather than inventing a new format. ### `proposal.md` - Fill missing: Why/Goals, In/Out of scope, Success metrics, Impact areas, Rollout/rollback, Risks, Open questions. - Keep it decision-light: proposal explains “what/why” and high-level impacts. ### `design.md` - Capture the chosen approach and trade-offs: architecture, data model, interfaces, failure handling, security, observability, migration/compat plan, alternatives, decision log. - If options were discussed, record: choice + rationale + rejected alternatives. ### `specs/*.md` (implementation-closest) Goal: make specs implementable and testable. Put details closest to code behavior here. - If this repo uses OpenSpec delta style, keep the required headers: - `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements` - `### Requirement: ...` - At least one `#### Scenario: ...` per requirement - Add concrete details: fields, examples, state transitions, error handling, auth rules, and acceptance criteria mapping. - Maintain traceability by linking: requirement → design decision → acceptance/test. If you restructure a file, append `## Appendix: Original Draft` and move the prior text there. ## Validation After write-back, validate and fix formatting issues using the repo’s OpenSpec CLI (not via Python runners). Try in this order: 1. If `openspec` is available on PATH: - `openspec validate --strict` 2. If not on PATH, try common repo-local entrypoints (use the first one that exists/is executable): - `./openspec validate --strict` - `./bin/openspec validate --strict` - `./tools/openspec validate --strict` - `./scripts/openspec validate --strict` 3. If none of the above exist, report that validation could not be run automatically and ask the user for the correct validation command for this repo. Do not guess. --- Source attribution: Rosetears520 Original project: https://github.com/Rosetears520/aili-notes License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gabriel Moreira Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: Rosetears520 Original project: https://github.com/Rosetears520/aili-notes Attribution basis: Upstream repository explicitly recorded in package mirror path Fields of work: Design, Development & Engineering, Operations, Product Management Roles: Business Process Analyst, Product Manager, QA / Test Engineer, Technical Product Manager, UX Designer Specialties: API Tools: Openspec Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 0e6f75c85e3e4ad6fc6f02c1875067293bf359d1e9ac1a69909534a9976a79e0