user-spec-planning

Name: user-spec-planning
Author: pavel-molyanov

241stars75forks

How to install user-spec-planning?

pavel-molyanov/molyanov-ai-dev/user-spec-planning

$npx -y skills add pavel-molyanov/molyanov-ai-dev --skill user-spec-planning

Installs into the current project.

Summary

Creates user-spec.md through adaptive interview with codebase scanning and dual validation. Use when: "сделай юзер спек", "проведи интервью для юзер спека", "создай юзерспек", "user spec", "detailed planning", "хочу продумать фичу", "опиши требования к фиче", "сделай описание фич

Files · 1

View on GitHub

SKILL.md

1	<!-- Generated by sync-to-codex v1. Do not edit directly. -->
2
3	# User Spec Planning
4
5	Thorough adaptive interview → codebase scan → user-spec.md → dual validation → user approval.
6	Output: `work/{feature}/user-spec.md` with status `approved`.
7
8	## Interview Style
9
10	Conduct the interview in the language the user writes in. Be thorough and opinionated — an engaged co-thinker who actively proposes solutions and challenges weak answers.
11
12	How to interview:
13	- 3-4 questions per batch. Run as many batches as needed until the cycle's items are fully covered.
14	- Propose solutions based on Project Knowledge (example in English): "architecture.md describes pattern X — I think we need Y here. Agree?"
15	- Challenge with substance — concrete counterexamples, code references, unexplored scenarios: "What if the user does Z? In the code, module Q doesn't handle this case."
16	- Accept the answer after one substantive challenge and move on to the next gap.
17	- When the user says "I don't know": help think through it (examples, common patterns). Optional item → mark TBD. Required item → break into simpler questions.
18
19	Interview depth depends on feature size (S/M/L in interview metadata):
20	- S (1-3 files, local fix): focused interview, core behavior
21	- M (several components): moderate depth, integration questions
22	- L (new architecture): deep interview, thorough edge cases and risk analysis
23
24	## Process
25
26	### Phase 0: Init
27
28	1. Check for existing interview: look in `work/*/logs/userspec/interview.yml` for `metadata.status: in_progress`. If found — load, show discussed topics summary, resume. If multiple found — show list, let user choose.
29	2. Get task description (ask in the user's language): "Describe what you want to do."
30	3. Determine work_type (feature / bug / refactoring) from description.
31	4. Propose feature name (kebab-case), get user confirmation.
32	5. Run `~/.claude/shared/scripts/init-feature-folder.sh {name}` — creates folder structure with interview.yml.
33	6. Update interview.yml: set metadata.started, metadata.status: in_progress, phase1_feature_overview.feature_name, phase1_feature_overview.work_type.
34
35	Checkpoint: interview.yml exists with status in_progress, feature name confirmed.
36
37	### Phase 1: Study Project Knowledge
38
39	Read ALL files from `.claude/skills/project-knowledge/references/`. If directory missing or empty — warn user, suggest running project-planning skill (or `/init-project-knowledge` command).
40
41	These files are your context for the entire interview. Reference them when asking questions and proposing solutions.
42
43	### Phase 2: Cycle 1 — General Understanding
44
45	Scope: `phase1_feature_overview` items in interview.yml.
46
47	1. Score user's initial description against all items (detailed 80-95%, brief 50-70%, vague 20-40%, not mentioned 0%).
48	2. Run interview loop (see below) on phase1_feature_overview items.
49	3. During this cycle — determine feature size S/M/L and agree on testing strategy:
50	- S: integration/E2E usually not needed — state why
51	- M: propose whether integration tests make sense, explain reasoning
52	- L: propose specific integration and E2E scope with justification
53
54	### Phase 3: Code Scanning
55
56	Launch `code-researcher` subagent (spawn_agent, opus) with feature path and feature description from Cycle 1.
57
58	After subagent completes — read `{feature_path}/code-research.md`. Use findings in Cycle 2 questions.
59
60	If during later phases a gap is discovered — launch `code-researcher` again with the specific question to investigate.
61
62	### Phase 4: Cycle 2 — Code-Informed Refinement
63
64	Scope: `phase2_user_experience` + `phase3_integration` items.
65
66	1. Summarize understanding (examples in English; ask in the user's language): "I understand the task as: [X]. I plan to do it like: [Y, based on code]."
67	2. Questions based on code findings: "Found module X that does Y — reuse it?"
68	3. Cover deploy and user actions (items `deploy_approach`, `manual_user_actions`):
69	- "Are manual steps needed to launch? (create a bot, get API keys, set up a service, register somewhere)"
70	- "How to deploy? What needs configuring? (CI/CD already exists, needs setup, manual deploy)"
71	- "How to verify it works after deploy? (MCP tools, curl, manual check)"
72	- "What can be checked during development, without deploy? (call an external API, run locally, check config, poke the UI on localhost, test a prompt)"
73	4. Run interview loop on phase2 + phase3 items.
74
75	### Phase 5: Cycle 3 — Review & Finalize
76
77	Scope: ALL items across all phases still below threshold.
78
79	Cleanup pass: revisit anything not fully covere

People who liked this also viewed

6 picks

Type

user-spec-planning

241stars75forks

View on GitHub

How to install user-spec-planning?

pavel-molyanov/molyanov-ai-dev/user-spec-planning

$npx -y skills add pavel-molyanov/molyanov-ai-dev --skill user-spec-planning

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<!-- Generated by sync-to-codex v1. Do not edit directly. -->
2
3	# User Spec Planning
4
5	Thorough adaptive interview → codebase scan → user-spec.md → dual validation → user approval.
6	Output: `work/{feature}/user-spec.md` with status `approved`.
7
8	## Interview Style
9
10	Conduct the interview in the language the user writes in. Be thorough and opinionated — an engaged co-thinker who actively proposes solutions and challenges weak answers.
11
12	How to interview:
13	- 3-4 questions per batch. Run as many batches as needed until the cycle's items are fully covered.
14	- Propose solutions based on Project Knowledge (example in English): "architecture.md describes pattern X — I think we need Y here. Agree?"
15	- Challenge with substance — concrete counterexamples, code references, unexplored scenarios: "What if the user does Z? In the code, module Q doesn't handle this case."
16	- Accept the answer after one substantive challenge and move on to the next gap.
17	- When the user says "I don't know": help think through it (examples, common patterns). Optional item → mark TBD. Required item → break into simpler questions.
18
19	Interview depth depends on feature size (S/M/L in interview metadata):
20	- S (1-3 files, local fix): focused interview, core behavior
21	- M (several components): moderate depth, integration questions
22	- L (new architecture): deep interview, thorough edge cases and risk analysis
23
24	## Process
25
26	### Phase 0: Init
27
28	1. Check for existing interview: look in `work/*/logs/userspec/interview.yml` for `metadata.status: in_progress`. If found — load, show discussed topics summary, resume. If multiple found — show list, let user choose.
29	2. Get task description (ask in the user's language): "Describe what you want to do."
30	3. Determine work_type (feature / bug / refactoring) from description.
31	4. Propose feature name (kebab-case), get user confirmation.
32	5. Run `~/.claude/shared/scripts/init-feature-folder.sh {name}` — creates folder structure with interview.yml.
33	6. Update interview.yml: set metadata.started, metadata.status: in_progress, phase1_feature_overview.feature_name, phase1_feature_overview.work_type.
34
35	Checkpoint: interview.yml exists with status in_progress, feature name confirmed.
36
37	### Phase 1: Study Project Knowledge
38
39	Read ALL files from `.claude/skills/project-knowledge/references/`. If directory missing or empty — warn user, suggest running project-planning skill (or `/init-project-knowledge` command).
40
41	These files are your context for the entire interview. Reference them when asking questions and proposing solutions.
42
43	### Phase 2: Cycle 1 — General Understanding
44
45	Scope: `phase1_feature_overview` items in interview.yml.
46
47	1. Score user's initial description against all items (detailed 80-95%, brief 50-70%, vague 20-40%, not mentioned 0%).
48	2. Run interview loop (see below) on phase1_feature_overview items.
49	3. During this cycle — determine feature size S/M/L and agree on testing strategy:
50	- S: integration/E2E usually not needed — state why
51	- M: propose whether integration tests make sense, explain reasoning
52	- L: propose specific integration and E2E scope with justification
53
54	### Phase 3: Code Scanning
55
56	Launch `code-researcher` subagent (spawn_agent, opus) with feature path and feature description from Cycle 1.
57
58	After subagent completes — read `{feature_path}/code-research.md`. Use findings in Cycle 2 questions.
59
60	If during later phases a gap is discovered — launch `code-researcher` again with the specific question to investigate.
61
62	### Phase 4: Cycle 2 — Code-Informed Refinement
63
64	Scope: `phase2_user_experience` + `phase3_integration` items.
65
66	1. Summarize understanding (examples in English; ask in the user's language): "I understand the task as: [X]. I plan to do it like: [Y, based on code]."
67	2. Questions based on code findings: "Found module X that does Y — reuse it?"
68	3. Cover deploy and user actions (items `deploy_approach`, `manual_user_actions`):
69	- "Are manual steps needed to launch? (create a bot, get API keys, set up a service, register somewhere)"
70	- "How to deploy? What needs configuring? (CI/CD already exists, needs setup, manual deploy)"
71	- "How to verify it works after deploy? (MCP tools, curl, manual check)"
72	- "What can be checked during development, without deploy? (call an external API, run locally, check config, poke the UI on localhost, test a prompt)"
73	4. Run interview loop on phase2 + phase3 items.
74
75	### Phase 5: Cycle 3 — Review & Finalize
76
77	Scope: ALL items across all phases still below threshold.
78
79	Cleanup pass: revisit anything not fully covere

People who liked this also viewed

6 picks

Type