# project-spec-refiner

> Refine a project plan into an implementation-ready spec via a structured Q&A interview. Use when the user asks to refine a spec, turn a plan into a spec/PRD/tech spec/requirements/acceptance criteria/milestones/backlog, or provides a project plan that needs clarity.

- Author: Krarilotus
- Repository: adrian-kriegel/world2data
- Version: 20260208143029
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/adrian-kriegel/world2data
- Web: https://mule.run/skillshub/@@adrian-kriegel/world2data~project-spec-refiner:20260208143029

---

---
name: project-spec-refiner
description: Refine a project plan into an implementation-ready spec via a structured Q&A interview. Use when the user asks to refine a spec, turn a plan into a spec/PRD/tech spec/requirements/acceptance criteria/milestones/backlog, or provides a project plan that needs clarity.
---

# Project Spec Refiner (Q&A Interviewer)

## Goal
Turn the user's [PROJECT PLAN] into a crisp, implementable specification by interviewing them one question at a time. Maintain:
- Spec Draft (living)
- Open Issues / Decisions (living)

## Interaction rules (strict)
1. Ask ONE question at a time (max 3 sub-questions). Wait for the user's answer before proceeding.
2. If the user's answer is ambiguous, ask ONE follow-up question, then continue.
3. If the user says TBD/unknown, capture it in Open Issues and move on.
4. After each user answer, respond with exactly:
- What I learned (1-3 bullets)
- Spec Draft Updates (only changed bullets/sections)
- Open Issues / Decisions (new/updated items)
- Then your next single question
5. Prefer concrete artifacts: examples, edge cases, data shapes, measurable KPIs, acceptance criteria.
6. Force testability: every requirement must have acceptance criteria.
7. If multiple approaches exist, present 2-3 options with tradeoffs and ask the user to choose.
8. If you must assume, label ASSUMPTION and add it to Open Issues for confirmation.

## Start condition (first message)
Begin by asking the user to provide:
- Their project plan (paste or summary)
- Hard constraints: deadline, budget, target users, deployment environment, tech stack, compliance/security constraints

## Stop condition (when to finalize)
Stop interviewing and produce the final deliverables when:
- Goals + non-goals are clear
- Core workflows are specified end-to-end (happy path + failure modes)
- Requirements are testable
- Data/integrations are defined enough to implement
- Architecture sketch + NFRs + milestones exist
- Remaining uncertainties are listed as Open Issues

## Interview map (use this order)
Use the checklist in references/INTERVIEW_CHECKLIST.md if needed.

1. Context & problem
- Who has the problem? What happens today? What triggers the need?

2. Objectives & success metrics
- KPIs/SLIs, definition of done, non-goals

3. Users & permissions
- Personas/roles, permission model, admin vs user behaviors

4. Scope & constraints
- In-scope/out-of-scope, assumptions, constraints, risks

5. Functional requirements
- Entities, user stories, workflows, edge cases, error handling

6. Non-functional requirements (NFRs)
- Performance, reliability, availability, observability
- Security, privacy, compliance, audit logs, retention

7. Data model & contracts
- IDs, schemas, events, validation, versioning

8. Integrations
- External APIs/services, auth, rate limits, retries, failure semantics

9. UX / interaction flows
- Screens/steps, empty states, error states, i18n/accessibility

10. Architecture & delivery plan
- Components, boundaries, deployment, CI/CD, migrations
- Milestones: MVP, next, later

## Output formats (final deliverables)
When finalizing, produce:
1. Refined Spec using references/SPEC_TEMPLATE.md
2. Prioritized backlog using references/BACKLOG_TEMPLATE.md
3. Open Issues / Decisions (final list)

## Acceptance criteria conventions
Use patterns from references/ACCEPTANCE_CRITERIA_PATTERNS.md. Prefer:
- Given/When/Then
- Explicit performance thresholds
- Clear error semantics
- Observable/loggable outcomes

## Example interviewing behavior
Prefer: "What is the primary user role, and what is the #1 workflow they must complete in under 2 minutes?"
Avoid: "Tell me more about the project" (too broad)

## Safety / scope hygiene
- Do not invent requirements the user did not imply.
- Keep a tight separation between MVP vs later enhancements.
- Never silently broaden scope; propose explicitly, then ask for a decision.