Builder Brief Writer
Write the briefs for a round of pyric's app-builder pilot, one JSON file per brief, aimed at the weak areas of the evidence map. Use when asked to write, check or revise builder briefs for a round. Not for running a round (bun test/builders/harness.ts round) or verifying one (builder-verifier).
mkdir -p ~/.claude/skills/builder-brief-writer && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/builder-brief-writer/SKILL.md' -o ~/.claude/skills/builder-brief-writer/SKILL.md
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Builder Brief Writer when an AI agent needs a reusable SKILL.md workflow for this job: Write the briefs for a round of pyric's app-builder pilot, one JSON file per brief, aimed at the weak areas of the evidence map. Use when asked to write, check or revise builder briefs for a round. Not for running a round (bun test/builders/harness.ts round) or verifying one (builder-verifier).
When not to use it
Skip Builder Brief Writer when the task is outside the writing category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/builder-brief-writer && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/builder-brief-writer/SKILL.md' -o ~/.claude/skills/builder-brief-writer/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/builder-brief-writer/SKILL.md. For a shared project, commit the folder at .claude/skills/builder-brief-writer/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Builder Brief Writer skill for this task: Use Builder Brief Writer when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 56/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Builder brief writer
Each brief sends one cheap builder at one weak area of pyric, pushed past the surface. A good brief makes a builder do something no existing check does, and names what production refuses so the builder has to try it.
## Inputs
Two directories, each a setting:
- the **ops directory**, `PYRIC_OPS_DIR` when it is set, otherwise `pyric-ops` in the home directory. It holds the evidence map and the ideas. - the **data root**, `PYRIC_BUILDERS_DATA_DIR` when it is set, otherwise `pyric-ops/assurance/builders` in the home directory, as `test/builders/round-paths.ts` resolves it. The harness reads briefs from it and keeps runs in it.
Read all three inputs before writing anything:
1. **Weak areas.** The evidence map, `<ops directory>/assurance/change-map-alpha30.md`, and the registry rows still `automation: "unverified"` in `packages/conformance/registry/*.ts`. An area is weak when it changed a lot since alpha.30 and no app scenario under `test/apps/` drives it, or when its rows are unverified. 2. **Ideas.** `<ops directory>/builder-ideas.md`: app ideas and the five stress dimensions (scale, lifecycle, integration, combination, concurrency). Use an idea when one fits the area. 3. **Production's behavior.** Firebase's own documentation on `firebase.google.com`. Every must-be-refused line cites one of its pages. Never call production to find out; a page is the evidence.
## Rules
- One target area per brief, and one or two stress dimensions. - The app must be buildable from pyric's public docs alone (`packages/site-docs/src/content/`): name each feature the way the docs name it. - Nothing in a brief needs production, a real credential, a deploy, or a native client (Android, iOS and Flutter are parked in #1048). - Two to five must-be-refused actions, each something a user of the app could do, with production's exact answer (an error code such as `permission-denied` or `storage/unauthorized`, or an HTTP status). - The model and the dollar cap are not in the brief: `round` runs each brief once per model at one cap. - Briefs of one round differ in area, so the comparison between models is per brief and the round covers more than one area.
## The file
One file per brief, `<data root>/briefs/<round>/<round>-<n>.json`. `test/builders/brief.ts` holds the shape; a field it doesn't name fails.
```json { "id": "r1-1", "targetArea": { "area": "one area from the evidence map", "whyWeak": "the evidence: commits since alpha.30, no scenario, unverified rows" }, "stressDimensions": ["combination"], "appIdea": "one paragraph", "framework": "next-16 | vite | node-server", "features": ["named as the docs name them"], "userJourney": ["what a person does, step by step"], "mustBeRefused": [ { "action": "another user's write under the given rules", "firebaseDoc": "https://firebase.google.com/docs/...", "productionAnswer": "permission-denied" } ], "limits": { "wallClockMinutes": 45 } } ```
`test/builders/fixtures/briefs/brief-1.json` is a complete example.
## Check
``` bun test/builders/harness.ts check-briefs <round> ```
validates every brief of the round as `round` would and starts nothing. Fix each error it names. Then tell David the round is ready: the briefs, the area each targets, and why that area is weak.
Intended uses
- Use Builder Brief Writer when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.