market-read-lab
Skill1 starsChanged 5 months agoApache-2.0View on GitHub
Use when starting, scaffolding, running, reviewing, or running autonomous Market Read Lab cycles in this Web Research / Truffle project. Handles numbered run folders, Scout/Read/Review gates, repo templates, the append-only learning stream, and the no-auto-graduation convention.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-build-decideSkill
- agent-build-proposeSkill
- agent-build-reviewSkill
- agent-learning-mineSkill
- commit-allSkill
- learning-reviewSkill
- review-changeSkill
- work-menuSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 7 are distinctive, and 13 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.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Use this skill for experiments/00-market-read-lab/.
- Very specific: line 19
Scaffold a run: use .claude/skills/market-read-lab/scripts/new_run.py.
- Very specific: line 20
Review selected-question history: use .claude/skills/market-read-lab/scripts/question_history.py.
- Very specific: line 21
Run Scout: use experiments/00-market-read-lab/templates/operator-scout-prompt.md.
- Very specific: line 22
Run Loop 1: use experiments/00-market-read-lab/templates/operator-loop1-prompt.md.
- Distinctive: line 24
Run one autonomous cycle: follow Autonomous Full Cycle below.
- Very specific: line 25
Run a learning pass: use the /learning-review skill with target market-read-lab (out-of-band consolidation.
- Very specific: line 29
Keep run artifacts outside store/.
- Very specific: line 30
Treat experiments/00-market-read-lab/templates/ and operator prompts as the current template authority.
- Very specific: line 32
Treat prior runs as evidence, not templates.
- Distinctive: line 37
Use only the selected run contract's allowed sources.
- Very specific: line 41
Stop at needs-human-review for live browsing outside a bounded plan, unplanned Firecrawl spend, broad external research, store/ mutation, …
- Distinctive: line 69
If a question is known but the run contract still needs Scout:
- Distinctive: line 117
After scaffolding, report the created run path and the printed prompt.
- Distinctive: line 121
Run exactly one Scout -> Loop 1 -> Loop 2 cycle in the current routine/session.
- Distinctive: line 122
Use file gates between stages.
- Very specific: line 124
Read the README, scout-context.md, learning/observations.md, learning/lessons.md, and the Scout/Loop 1/Loop 2 operator prompts.
- Very specific: line 136
Run Scout against the created path, following the current question-selection policy in scout-context.md: select for value + reach + roadmap …
- Very specific: line 151
Run Loop 1 against the current target path.
- Distinctive: line 165
If fresh worker sessions are available, they may run individual stages.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
$ARGUMENTS
Purpose
Use this skill for experiments/00-market-read-lab/.
Market Read Lab runs repeated market reads to learn which source ingredients, category/cohort questions, relation shapes, and non-company evidence Truffle actually needs. Persist the runs, not the ontology.
Route
- Scaffold a run: use
.claude/skills/market-read-lab/scripts/new_run.py. - Review selected-question history: use
.claude/skills/market-read-lab/scripts/question_history.py. - Run Scout: use
experiments/00-market-read-lab/templates/operator-scout-prompt.md. - Run Loop 1: use
experiments/00-market-read-lab/templates/operator-loop1-prompt.md. - Run Loop 2: use
experiments/00-market-read-lab/templates/operator-loop2-prompt.md. - Run one autonomous cycle: follow Autonomous Full Cycle below.
- Run a learning pass: use the
/learning-reviewskill with targetmarket-read-lab(out-of-band consolidation; not per run).
Invariants
- Keep run artifacts outside
store/. - Treat
experiments/00-market-read-lab/templates/and operator prompts as the current template authority. - Treat prior runs as evidence, not templates. Runs
000-003are historical or incomplete pre-contract runs; do not copy their headers, source rigor, stage behavior, or artifact shape. - Name runs
NNN-YYYY-MM-DD-short-slug/. - Advance stages only by
run_statusinrun-notes.md. - Use only the selected run contract's allowed sources.
bounded-liveis allowed only when the Selected Run Contract includes a filledlive_evidence_planwithbudget_class: light, ceilings, and fail-closed rules; every outside source must be logged inrun-notes.mdlive_evidence_used.- Stop at
needs-human-reviewfor live browsing outside a bounded plan, unplanned Firecrawl spend, broad external research,store/mutation, write-back, durable primitive creation, or lesson graduation. - For current/news/policy/pricing claims, treat snippets as leads. Use confident language only after receipts capture exact URLs, capture dates, source type, and primary/secondary status.
- Candidate questions live in run
scout.mdfiles unless Brian explicitly creates a shared question queue.learning/lessons.mdandlearning/observations.mdare context, not a question backlog. - Raw observations, wishes, frictions, surprises, and gap findings live first in
run-notes.mdObservations, then inexperiments/00-market-read-lab/learning/observations.md. Singletons are valid learning. Every reviewed run must leave observation rows, even if the row is a "no new raw learning" note. - Runs append observations only. Proposing lessons, writing
learning/lessons.md/learning/brian.md/learning/passes/, and graduating a lesson are out-of-band and human-gated, never a run stage.
Scaffold a New Run
Default Scout-only scaffold:
python3 .claude/skills/market-read-lab/scripts/new_run.py --slug "short-slug"This creates only scout.md, run-notes.md, and receipts/.gitkeep.
If a question is known but the run contract still needs Scout:
python3 .claude/skills/market-read-lab/scripts/new_run.py \
--slug "short-slug" \
--question "Question to sharpen into a run contract?"Print a Loop 1 prompt only for a contract-ready run:
python3 .claude/skills/market-read-lab/scripts/new_run.py \
--slug "short-slug" \
--question "Question to answer?" \
--mode loop1 \
--evidence-mode store-only \
--expected-denominator "Store companies matching the selected offer/category criteria." \
--allowed-source "store/" \
--allowed-source "experiments/00-market-read-lab/learning/" \
--builder-lens "Tests whether existing local State can carry the market read without a durable primitive." \
--reach-reason "Tests a useful reader question against a bounded local substrate." \
--why-autonomous-safe "Answerable from local store files and existing lab artifacts." \
--loop1-failure-mode "Overstating completeness from a partial denominator."Contract-ready bounded-live scaffold:
python3 .claude/skills/market-read-lab/scripts/new_run.py \
--slug "short-slug" \
--question "Question to answer?" \
--mode loop1 \
--evidence-mode bounded-live \
--expected-denominator "Store cohort plus a small external source panel." \
--allowed-source "store/" \
--allowed-source "approved bounded-live source families from live_evidence_plan" \
--builder-lens "Tests which outside source family exposes the missing market denominator." \
--reach-reason "Uses a small external panel to test a gap the store cannot settle alone." \
--live-evidence-goal "Verify the load-bearing current/source-panel claims." \
--source-family-allowed "SERP/listicle" \
--source-family-allowed "review/forum" \
--why-autonomous-safe "Standing bounded-live policy; light source panel only; no write-back." \
--loop1-failure-mode "Broadening from source check into open-ended browsing."Contract-ready Loop 1 scaffolds also create read.md. Review files are stage artifacts;
create them from templates only when Loop 2 runs.
After scaffolding, report the created run path and the printed prompt.
Autonomous Full Cycle
Run exactly one Scout -> Loop 1 -> Loop 2 cycle in the current routine/session. Use file gates between stages; do not hand off by updating scheduled tasks.
- Read the README,
scout-context.md,learning/observations.md,learning/lessons.md, and the Scout/Loop 1/Loop 2 operator prompts. Runquestion_history.pybefore Scout selection so prior selected-question shapes inform the gap check. Treatlearning/lessons.md,learning/observations.md, and the last 3 completedrun-notes.mdas post-candidate pressure checks perscout-context.md, not as question sources. Scaffold a temporary Scout run:
python3 .claude/skills/market-read-lab/scripts/new_run.py --slug "scout-candidates"- Run Scout against the created path, following the current question-selection
policy in
scout-context.md: select for value + reach + roadmap learning, not store-answerability. - Gate on
run-notes.mdand the Selected Run Contract. Continue only when:run_status: scout-only,autonomous_eligible: yes,approval_needed: no, andevidence_modeisstore-only,local-existing, orbounded-livewith a filledlive_evidence_planincluding ceilings and fail-closed rules. Rename the run before Loop 1:
python3 .claude/skills/market-read-lab/scripts/rename_run.py TARGET_RUN_PATHrename_run.pyprefersselected_slugfromscout.mdand falls back to the selected question.- Run Loop 1 against the current target path. If
read.mdis missing, create it fromtemplates/read.mdafter the stage gate passes. Preserve raw learning in the run-notes Observations section before learning tags. Continue only if Loop 1 ends withrun_status: read-done. - For Loop 2, prefer a quick workflow if the environment supports one. Use an
adversarial verification shape with three focused passes: evidence verifier,
consumer reviewer, and developer reviewer. If workflows are unavailable, run
Loop 2 normally from the operator prompt. If review files are missing, create them
from
templates/consumer-review.mdandtemplates/developer-review.mdafter the stage gate passes. Append preserved and review-discovered raw learning toexperiments/00-market-read-lab/learning/observations.md. Do not setrun_status: revieweduntil the observation stream has rows for this run. - Stop after review.
If fresh worker sessions are available, they may run individual stages. The parent routine still owns each gate: re-read artifacts after every stage before continuing.
Final report:
- run path
- final
run_status termination_reason- stage reached
- files touched
- observation rows added
- any approval or evidence block
Stage Notes
Scout writes only scout.md and the YAML header in run-notes.md. It should fill the
Selected Run Contract, including selected_slug, question_mode, builder_lens, and
reach_reason, and leave the run at scout-only only when the selected question is
safe to run unattended. A bounded gap-probe is valid when the source panel and stop
rules are clear.
Loop 1 writes only read.md, run-notes.md, and receipts. It creates read.md from
the template if needed, but only after the run_status: scout-only gate passes. It
must fail closed unless the Scout contract is complete, autonomous-safe, and
source-bounded. It fills the read.md Gap Map and run-notes.md Observations even
when the direct answer is partial. For bounded-live, it must also log every outside
source in live_evidence_used, record spend notes, enforce the selected ceilings, and
stop with insufficient-evidence instead of expanding beyond the plan.
Loop 2 writes consumer-review.md, developer-review.md, and the run's observation
rows in learning/observations.md. It creates review files from templates if needed,
but only after the run_status: read-done gate passes. It appends observations only —
it does not propose lessons, write learning/lessons.md / learning/brian.md /
learning/passes/, graduate anything, or implement system changes.
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.

