writing-briefs
Skill1 starsChanged 3 months agoMITView on GitHub
Use when turning a feature idea, product problem, UX change, or uncertain request into a high-level requirements brief before writing a technical spec or implementation plan, especially when scope, user value, non-goals, acceptance criteria, or requirement trade-offs need alignment.
In this repository5 other files it gives its agents.
- dual-reviewSkill
- english-learning-card-imageSkill
- writing-plansSkill
- writing-specsSkill
- xibin-douyin-script-extractorSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use the project's normal language for the generated brief.
- Distinctive: line 20
Check project rules and nearby briefs, specs, and plans before writing.
- Distinctive: line 23
Ask only for missing information that would change the requirement.
- Distinctive: line 25
After the user approves the brief, continue to the appropriate design or spec workflow.
- Distinctive: line 66
Before handing off the brief, check:
- Distinctive: line 69
Every goal and acceptance criterion is observable in the product or user workflow.
- Distinctive: line 70
Every non-goal actually removes scope.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing Briefs
Overview
Write a brief when the next useful artifact is requirement alignment, not technical design. A brief answers what problem to solve, for whom, what must be true when done, and what is deliberately out of scope. Specs decide how to satisfy it; plans decide how to implement it.
Use the project's normal language for the generated brief. Keep this skill itself generic and compact.
Default Location
Save briefs to docs/briefs/YYYY-MM-DD-<topic>-brief.md unless project rules or the user specify another location. Preserve existing historical paths rather than renaming them for this skill.
Workflow
- Check project rules and nearby briefs, specs, and plans before writing.
- Restate the request as a verifiable requirement goal.
- Separate product decisions from implementation details. Keep code paths, event chains, schemas, libraries, and patch steps out unless they are explicit user-facing constraints.
- Ask only for missing information that would change the requirement. Otherwise make the most reasonable assumption, label it, and continue.
- Draft the brief, then self-review it before saving or presenting.
- After the user approves the brief, continue to the appropriate design or spec workflow. If a spec or plan already exists, revise it against the approved brief before implementation.
Brief Template
# <Feature or Change> - Brief
- Date: YYYY-MM-DD
- Status: Brief pending review
- Links: <existing spec, plan, issue, or source request if any>
## Problem
<What is broken, missing, confusing, costly, or risky from the user's point of view.>
## Users and Scenarios
<Who experiences this, and in what concrete workflow.>
## Goals
- <User-visible outcome 1>
- <User-visible outcome 2>
## Non-Goals
- <Scope intentionally excluded from this change>
## Requirements
- <Observable behavior or rule>
- <Observable behavior or rule>
## Acceptance Criteria
- <How a reviewer or user can tell the requirement is satisfied>
- <Important regression that must remain unchanged>
## Constraints and Assumptions
- <Product, platform, privacy, performance, compatibility, or policy constraint>
## Open Questions
- <Only questions that would change the requirement or scope>Quality Bar
Before handing off the brief, check:
- A non-engineer stakeholder can change the desired behavior without reading implementation details.
- Every goal and acceptance criterion is observable in the product or user workflow.
- Every non-goal actually removes scope.
- Technical details are either absent or explicitly justified as user-facing constraints.
- Open questions are few and decision-relevant; routine implementation questions belong in the spec.
Common Mistakes
| Mistake | Fix |
| Writing a design doc under a brief title | Move architecture, code paths, data flow, and event semantics to the spec. |
| Skipping non-goals | Add exclusions before scope leaks into the spec and plan. |
| Asking the user to choose every detail | Recommend the default, record the assumption, and ask only when it changes scope. |
| Treating the plan as source of truth | The approved brief governs the spec and plan; update downstream documents when requirements change. |
| Vague acceptance criteria | Rewrite them as observable outcomes or concrete regression checks. |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.