{"_id":"@alex.botez/clarifying-ideas","name":"@alex.botez/clarifying-ideas","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alex.botez/clarifying-ideas","version":"1.0.0","description":"An agent skill that helps you turn vague ideas into structured requirements","type":"module","repository":{"type":"git","url":"git+https://github.com/alexbot/clarifying-ideas.git"},"homepage":"https://github.com/alexbot/clarifying-ideas#readme","bugs":{"url":"https://github.com/alexbot/clarifying-ideas/issues"},"exports":{"./durable":{"types":"./dist/durable/index.d.ts","import":"./dist/durable/index.js"},"./interview":{"types":"./dist/interview/index.d.ts","import":"./dist/interview/index.js"},"./phases":{"types":"./dist/phases/index.d.ts","import":"./dist/phases/index.js"},"./skill":{"types":"./dist/skill/index.d.ts","import":"./dist/skill/index.js"}},"scripts":{"build":"tsc","build:skill":"node scripts/build-skill.mjs","deploy:skill":"node scripts/build-skill.mjs && node -e \"const fs=require('fs');fs.mkdirSync('.claude/skills/clarifying-ideas/scripts',{recursive:true});fs.copyFileSync('skills/clarifying-ideas/SKILL.md','.claude/skills/clarifying-ideas/SKILL.md');fs.copyFileSync('skills/clarifying-ideas/scripts/clarifying-ideas.cjs','.claude/skills/clarifying-ideas/scripts/clarifying-ideas.cjs');fs.copyFileSync('skills/clarifying-ideas/scripts/clarifying-ideas.cjs.map','.claude/skills/clarifying-ideas/scripts/clarifying-ideas.cjs.map')\" && echo Deployed to .claude/skills/clarifying-ideas/","dev":"tsc --watch","test":"vitest","test:run":"vitest run","eval":"vitest run --config vitest.eval.config.ts","lint":"eslint src/","typecheck":"tsc --noEmit"},"keywords":["ai","agent-skill","claude-code","discovery","elaboration","interview","project-scoping","requirements","socratic","specification"],"license":"MIT","devDependencies":{"@ai-sdk/anthropic":"^3.0.71","@ai-sdk/google":"^3.0.64","@ai-sdk/openai":"^3.0.53","@openrouter/ai-sdk-provider":"^2.9.0","@types/node":"^20.0.0","ai":"^6.0.168","esbuild":"^0.27.4","eslint":"^9.0.0","typescript":"^5.0.0","typescript-eslint":"^8.0.0","vitest":"^2.0.0","zod-to-json-schema":"^3.25.2"},"dependencies":{"yaml":"^2.8.3","zod":"^3.0.0"},"engines":{"node":">=22.0.0"},"gitHead":"75dae14c5574bfe2ed89b0531517174bef0c020e","_id":"@alex.botez/clarifying-ideas@1.0.0","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-jNUNx7UqXKvmPlH+ln+I3NX6Pf2ogcWEY5A+1IIe97aJTbjp5GK+72YJOp+HaByvVjRhogB6Xy/T5acHuhdtPg==","shasum":"7630aef9a4380df112e5c8d3a41e3f2c7a1bb06d","tarball":"https://registry.npmjs.org/@alex.botez/clarifying-ideas/-/clarifying-ideas-1.0.0.tgz","fileCount":163,"unpackedSize":1127459,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDlFDSeJRj6Clhy0Er//GSpYpq4+DRiWqbIy6LTKFW11AiBIyLDyPoTWTJZXvmHFL3Bv1+6ja+mJgnCiCMQaEe0IIQ=="}]},"_npmUser":{"name":"alex.botez.user","email":"alex.botez@gmail.com"},"directories":{},"maintainers":[{"name":"alex.botez.user","email":"alex.botez@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clarifying-ideas_1.0.0_1782252285317_0.04211158362380951"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-23T22:04:45.186Z","1.0.0":"2026-06-23T22:04:45.512Z","modified":"2026-06-23T22:04:45.718Z"},"maintainers":[{"name":"alex.botez.user","email":"alex.botez@gmail.com"}],"description":"An agent skill that helps you turn vague ideas into structured requirements","homepage":"https://github.com/alexbot/clarifying-ideas#readme","keywords":["ai","agent-skill","claude-code","discovery","elaboration","interview","project-scoping","requirements","socratic","specification"],"repository":{"type":"git","url":"git+https://github.com/alexbot/clarifying-ideas.git"},"bugs":{"url":"https://github.com/alexbot/clarifying-ideas/issues"},"license":"MIT","readme":"# Clarifying Ideas\n\nAn agent skill that helps you turn vague ideas into structured requirements.\n\n[![CI](https://github.com/alexbot/clarifying-ideas/actions/workflows/ci.yml/badge.svg)](https://github.com/alexbot/clarifying-ideas/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@alex.botez/clarifying-ideas)](https://www.npmjs.com/package/@alex.botez/clarifying-ideas)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n## The Problem\n\nMost people either vibe-code, start building and figure it out along the way, or paste a one-line prompt and hope what comes back is a spec. Both skip the step before planning: figuring out what success looks like, who cares, where the boundaries are, and which assumptions will bite you later.\n\n```\n             Most projects start here\n                        ↓\n        ┌──────┐    ┌────────┐    ┌───────┐    ┌──────┐    ┌────────┐\n  ?  →  │ Plan │ →  │ Design │ →  │ Build │ →  │ Test │ →  │ Launch │\n        └──────┘    └────────┘    └───────┘    └──────┘    └────────┘\n  ↑\n  Clarifying Ideas sits here.\n```\n\nThat step has methods (qualitative research, goal modeling, structured interviews) but they depend on trained facilitators and workshops. Solo developers, founders, and small teams skip it entirely, and discover the gaps mid-build.\n\n## Quick Start\n\n```bash\nnpx skills add alexbot/clarifying-ideas -a claude-code      # Claude Code\nnpx skills add alexbot/clarifying-ideas -a cursor            # Cursor\nnpx skills add alexbot/clarifying-ideas -a github-copilot    # GitHub Copilot\n```\n\nThen `/clarifying-ideas` in your agent. Any agent that supports [agentskills.io](https://agentskills.io) works. See the [full list](https://www.npmjs.com/package/skills#supported-agents).\n\n## What It Does\n\nClarifying Ideas asks the right questions, 25–32 across seven phases, and you control every answer. It moves you from a vague idea to a scoped project definition.\n\n- Catches gaps you'd miss on your own: undefined success criteria, wrong assumptions, conflicting premises nobody stated\n- Every goal, stakeholder, scope decision, and assumption traces back to the conversation turn that produced it\n- AI flags ambiguity, never self-resolves. You decide everything\n\n## Example\n\nThe vague idea:\n\n> *\"Our local library branch is losing visitors and the city might close it. I want to help revive it.\"*\n\nWhat AI generates from that prompt, versus what emerges after 28 Clarifying Ideas questions:\n\n| | AI-generated | After Clarifying Ideas |\n|---|---|---|\n| **Purpose** | **Increase traffic by 40%** through events, outreach, and digital resources | **Determine whether the library is what the neighborhood actually needs** |\n| **Goals** | 8 goals with **invented metrics**: 2,500 monthly visitors, $15K fundraising, 30% card registration increase | 3 goals that **flag unknowns**: what patrons actually need, what the city's closure criteria are, who the target visitors should be |\n| **Scope** | **Execution**: launch 5 programs, recruit 15 volunteers, secure grants | **Research**: talk to families, interview city council, assess whether the library is even the right solution |\n| **Insight** | \"The library is **a critical community asset**\" (stated as fact) | \"I never stopped to ask **whether the library is actually what the neighborhood needs**\" |\n\n[AI-generated brief](docs/examples/library.brief.generated.md) · [Clarifying Ideas brief](docs/examples/library.brief.md) · [More examples](docs/examples/)\n\n## Output\n\nThe interview produces two artifacts:\n\n- **Session file** (`.clarifying-ideas/session.yaml`). YAML with every goal, stakeholder, scope item, and assumption traced to its conversation turn. Designed as input for spec-driven development tools or any pipeline that needs structured intent.\n- **Project brief.** Run `/project-brief` on the session to generate a readable markdown summary for stakeholder pitches, project kickoffs, or business plans.\n\nThe session file lives in your project directory. AI coding agents (Claude Code, Cursor, Aider, etc.) can read it directly — no conversion or extra setup needed. Point your agent at the file and it has the full structured context from the interview.\n\n## How It Works\n\nThe interview is complex: 7 phases, state persistence, extraction cycles, deviation handling. The phases are opening, purpose, goals, stakeholders, scope, assumptions, and validation. Rather than relying on the model to follow a long prompt correctly, Clarifying Ideas splits the work. A compiled script handles all process decisions (what to ask, when to transition, how to store artifacts) while the model handles only semantic work (understanding what you said, extracting meaning, composing follow-ups). The model can't skip phases or lose track; the script drives.\n\nInterview techniques draw on Kvale & Patton (semi-structured interviewing), Miller & Rollnick (motivational interviewing), Reynolds & Gutman (means-end laddering), and KAOS (goal decomposition). See [docs/decisions/](docs/decisions/) for the full architecture story.\n\n## Security\n\nClarifying Ideas runs locally. No telemetry, no analytics, no data sent anywhere. There are no postinstall scripts — `npm install` runs nothing. All writes go to `.clarifying-ideas/` inside your project directory; nothing touches shared caches, home directories, or system paths.\n\n## Development\n\nRequires **Node 22+**.\n\n```bash\nnpm install\nnpm run build          # TypeScript compilation\nnpm run build:skill    # esbuild bundle → dist/skill/\nnpx vitest run         # Run tests\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, and how to pick up work.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md","_rev":"1-60da680afb85a9755ebc6ff501a3d412"}