user-alignment

Name: user-alignment
Author: tryproduck

487stars7forks

How to install user-alignment?

tryproduck/produck-skills/user-alignment

$npx -y skills add tryproduck/produck-skills --skill user-alignment

Installs into the current project.

Summary

Use when turning a vague or messy user request into an aligned, agent-executable PRD. Converts raw requests into testable specs with scope, phases, acceptance criteria, and explicit do-not-do boundaries for coding agents. Triggers on planning a feature from a rough ask, writing a

Files · 1

View on GitHub

SKILL.md

1	# User Alignment & Agent-Executable PRDs
2
3	Purpose: A practical guide for turning messy user requests into aligned, testable Product Requirements Documents (PRDs) that autonomous or semi-autonomous agents can execute without drifting.
4
5	> Two supporting files ship with this skill:
6	> - [`references/prd-template.md`](references/prd-template.md) — the full copy-paste agent-executable PRD template.
7	> - [`references/reading-list.md`](references/reading-list.md) — the research and reference map this guide is built on.
8
9	---
10
11	## 1. Core thesis
12
13	A good agent PRD is not just a product document. It is a shared operating contract between the user, the product owner, and the implementation agent.
14
15	It must do three jobs at once:
16
17	1. Align on user intent — what the user actually wants, why it matters, and what outcome would make them say “yes, that’s it.”
18	2. Remove ambiguity before execution — especially around scope, constraints, priorities, edge cases, and trade-offs.
19	3. Translate intent into executable work — sequenced phases, explicit files/systems, acceptance criteria, tests, and “do not do” boundaries.
20
21	For human teams, ambiguity can be resolved in meetings. Agents often resolve ambiguity by guessing. The PRD’s job is to make guessing unnecessary.
22
23	---
24
25	## 2. Research-backed principles
26
27	### 2.1 Start with the user problem, not the implementation
28
29	AI/product PRDs should begin with the user pain and the cost of the status quo, not with “we will use AI/model/tool X.” The model, framework, or agent is an implementation detail unless the user explicitly constrained it.
30
31	A strong problem statement should include:
32
33	- Who is affected.
34	- What they are trying to accomplish.
35	- What blocks them today.
36	- Why existing/manual/deterministic solutions are insufficient.
37	- What measurable improvement would matter.
38
39	Bad: “Build an AI assistant for support.”
40	Better: “Support agents spend 8 minutes triaging each ticket, and 23% are misrouted. We need ticket classification under 2 seconds with at least 92% routing accuracy, while escalating low-confidence cases.”
41
42	### 2.2 Treat the PRD as an executable artifact
43
44	Spec-driven development treats the spec as a durable source of truth, not disposable planning scaffolding. The spec should be checked into the repo and referenced by agents across sessions.
45
46	The PRD should answer:
47
48	- What should be built?
49	- Why does it matter?
50	- What is explicitly out of scope?
51	- What order should work happen in?
52	- How will each phase be verified?
53	- What should the agent never touch?
54
55	### 2.3 Write for two audiences: humans first, agents second
56
57	The top of the PRD should explain the product and user context in human language. The lower sections should become increasingly operational and literal for the agent.
58
59	Recommended split:
60
61	\| Section type \| Audience \| Style \|
62	\| --- \| --- \| --- \|
63	\| Problem, users, goals, success metrics \| Humans + agents \| Clear prose, rationale, trade-offs \|
64	\| Scope, constraints, edge cases \| Humans + agents \| Structured bullets/tables \|
65	\| Phases, tasks, tests, commands \| Agents \| Explicit, sequential, verifiable \|
66	\| “Do not do” instructions \| Agents \| Direct prohibitions, no nuance \|
67
68	### 2.4 Break work into bounded phases
69
70	Traditional PRDs often describe the whole product and leave sequencing to engineers. Agent PRDs should define implementation phases with dependencies and testable outputs.
71
72	Each phase needs:
73
74	- Dependency: what must already exist.
75	- Scope: what this phase covers.
76	- Out of scope: adjacent work the agent must not do yet.
77	- Tasks: concrete implementation actions.
78	- Verification: commands, tests, screenshots, or manual checks that prove completion.
79
80	### 2.5 Define evaluation before implementation
81
82	For AI or agentic features, “works” is rarely binary. Define launch thresholds, target thresholds, and aspirational thresholds before building.
83
84	Include three metric classes:
85
86	1. Outcome metrics — user/business result, e.g. completion rate, time saved, conversion lift.
87	2. Quality metrics — correctness, relevance, tone, completeness, usefulness.
88	3. Operational metrics — latency, cost, reliability, throughput, escalation rate.
89
90	For agent-executed software projects, also define:
91
92	- Unit/integration/e2e tests required.
93	- Manual QA checks.
94	- Review criteria.
95	- Regression risks.
96	- Expected screenshots or artifacts.
97
98	### 2.6 Make constraints and prohibitions explicit
99
100	Agents overbuild when boundaries are unclear. Every PRD should include an explicit “do not do” section.
101
102	Examples:
103
104	- Do not change auth

People who liked this also viewed

6 picks

Type

user-alignment

487stars7forks

View on GitHub

How to install user-alignment?

tryproduck/produck-skills/user-alignment

$npx -y skills add tryproduck/produck-skills --skill user-alignment

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# User Alignment & Agent-Executable PRDs
2
3	Purpose: A practical guide for turning messy user requests into aligned, testable Product Requirements Documents (PRDs) that autonomous or semi-autonomous agents can execute without drifting.
4
5	> Two supporting files ship with this skill:
6	> - [`references/prd-template.md`](references/prd-template.md) — the full copy-paste agent-executable PRD template.
7	> - [`references/reading-list.md`](references/reading-list.md) — the research and reference map this guide is built on.
8
9	---
10
11	## 1. Core thesis
12
13	A good agent PRD is not just a product document. It is a shared operating contract between the user, the product owner, and the implementation agent.
14
15	It must do three jobs at once:
16
17	1. Align on user intent — what the user actually wants, why it matters, and what outcome would make them say “yes, that’s it.”
18	2. Remove ambiguity before execution — especially around scope, constraints, priorities, edge cases, and trade-offs.
19	3. Translate intent into executable work — sequenced phases, explicit files/systems, acceptance criteria, tests, and “do not do” boundaries.
20
21	For human teams, ambiguity can be resolved in meetings. Agents often resolve ambiguity by guessing. The PRD’s job is to make guessing unnecessary.
22
23	---
24
25	## 2. Research-backed principles
26
27	### 2.1 Start with the user problem, not the implementation
28
29	AI/product PRDs should begin with the user pain and the cost of the status quo, not with “we will use AI/model/tool X.” The model, framework, or agent is an implementation detail unless the user explicitly constrained it.
30
31	A strong problem statement should include:
32
33	- Who is affected.
34	- What they are trying to accomplish.
35	- What blocks them today.
36	- Why existing/manual/deterministic solutions are insufficient.
37	- What measurable improvement would matter.
38
39	Bad: “Build an AI assistant for support.”
40	Better: “Support agents spend 8 minutes triaging each ticket, and 23% are misrouted. We need ticket classification under 2 seconds with at least 92% routing accuracy, while escalating low-confidence cases.”
41
42	### 2.2 Treat the PRD as an executable artifact
43
44	Spec-driven development treats the spec as a durable source of truth, not disposable planning scaffolding. The spec should be checked into the repo and referenced by agents across sessions.
45
46	The PRD should answer:
47
48	- What should be built?
49	- Why does it matter?
50	- What is explicitly out of scope?
51	- What order should work happen in?
52	- How will each phase be verified?
53	- What should the agent never touch?
54
55	### 2.3 Write for two audiences: humans first, agents second
56
57	The top of the PRD should explain the product and user context in human language. The lower sections should become increasingly operational and literal for the agent.
58
59	Recommended split:
60
61	\| Section type \| Audience \| Style \|
62	\| --- \| --- \| --- \|
63	\| Problem, users, goals, success metrics \| Humans + agents \| Clear prose, rationale, trade-offs \|
64	\| Scope, constraints, edge cases \| Humans + agents \| Structured bullets/tables \|
65	\| Phases, tasks, tests, commands \| Agents \| Explicit, sequential, verifiable \|
66	\| “Do not do” instructions \| Agents \| Direct prohibitions, no nuance \|
67
68	### 2.4 Break work into bounded phases
69
70	Traditional PRDs often describe the whole product and leave sequencing to engineers. Agent PRDs should define implementation phases with dependencies and testable outputs.
71
72	Each phase needs:
73
74	- Dependency: what must already exist.
75	- Scope: what this phase covers.
76	- Out of scope: adjacent work the agent must not do yet.
77	- Tasks: concrete implementation actions.
78	- Verification: commands, tests, screenshots, or manual checks that prove completion.
79
80	### 2.5 Define evaluation before implementation
81
82	For AI or agentic features, “works” is rarely binary. Define launch thresholds, target thresholds, and aspirational thresholds before building.
83
84	Include three metric classes:
85
86	1. Outcome metrics — user/business result, e.g. completion rate, time saved, conversion lift.
87	2. Quality metrics — correctness, relevance, tone, completeness, usefulness.
88	3. Operational metrics — latency, cost, reliability, throughput, escalation rate.
89
90	For agent-executed software projects, also define:
91
92	- Unit/integration/e2e tests required.
93	- Manual QA checks.
94	- Review criteria.
95	- Regression risks.
96	- Expected screenshots or artifacts.
97
98	### 2.6 Make constraints and prohibitions explicit
99
100	Agents overbuild when boundaries are unclear. Every PRD should include an explicit “do not do” section.
101
102	Examples:
103
104	- Do not change auth

People who liked this also viewed

6 picks

Type