← back to Cli Printing Press
fix(skills): tighten human-time-estimate cardinal rule + clean up violations (#452)
c78cb18130c28183c79507d42279c99e854e7995 · 2026-04-30 16:34:15 -0700 · Trevin Chow
Closes #206.
The cardinal rule against human-time estimates already existed at
SKILL.md:86 but the skill itself violated it 6 times. Per the issue:
agents are bad at estimating sub-task wall-clock, and quoted ranges
like "~15-20 min" for agent-driven work train users to distrust the
prompts.
Strengthen the rule to clearly distinguish the two cases:
- Sub-task estimates ("~15-30 min", "polish takes 10-20 minutes") are
agent-fabricated and BANNED. Describe scope instead.
- Wall-clock estimates for genuinely time-bound things are CARVED OUT:
the whole-CLI run (most take 30+ min — set the user's expectation up
front), tool installs (~10s for `go install`), and printing-press
subcommands that do network-bound work (crowd-sniff scans npm +
GitHub, ~5-10 min).
Per-violation:
- Lines 262 + 315 ("10-40 minutes depending on API complexity"): bumped
to "30-60 minutes." User feedback: 10-40 min was understated; most
CLIs take 30+ min.
- Line 547 ("Generate a fresh CLI ... ~15-20 min"): dropped. This was
a fabricated sub-task estimate inside an `AskUserQuestion` option.
- Lines 1037 + 1047 (crowd-sniff prompt "typically 2-4 minutes"):
bumped to "5-10 minutes" per user guidance. The 2-4 min figure came
from a March 2026 best-practice doc that was never instrumented;
5-10 min is the realistic post-2026 wall-clock for a typical npm +
GitHub scan.
- Line 1020 (crowd-sniff time budget): bumped from "5 minutes" to
"10 minutes" so the agent-side fallback timeout matches the
user-prompt range. Without this bump the prompt would promise up
to 10 min but the agent would fall back at 5.
- docs/solutions/.../sniff-and-crowd-sniff-complementary-discovery-2026-03-30.md
source-of-truth doc: bumped from 2-4 to 5-10 min for consistency.
Skipped (legitimate, not violations):
- Line 828 references the actual 3-minute budget rule.
- references/setup-checks.md "10 seconds" for `go install` is real
wall-clock, not agent-bound.
- Lines 903-905, 1110, 1128, 1134, 1798: real time budgets enforced
by fallback rules, not user-prompt estimates.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Files touched
M docs/solutions/best-practices/sniff-and-crowd-sniff-complementary-discovery-2026-03-30.mdM skills/printing-press/SKILL.md
Diff
commit c78cb18130c28183c79507d42279c99e854e7995
Author: Trevin Chow <trevin@trevinchow.com>
Date: Thu Apr 30 16:34:15 2026 -0700
fix(skills): tighten human-time-estimate cardinal rule + clean up violations (#452)
Closes #206.
The cardinal rule against human-time estimates already existed at
SKILL.md:86 but the skill itself violated it 6 times. Per the issue:
agents are bad at estimating sub-task wall-clock, and quoted ranges
like "~15-20 min" for agent-driven work train users to distrust the
prompts.
Strengthen the rule to clearly distinguish the two cases:
- Sub-task estimates ("~15-30 min", "polish takes 10-20 minutes") are
agent-fabricated and BANNED. Describe scope instead.
- Wall-clock estimates for genuinely time-bound things are CARVED OUT:
the whole-CLI run (most take 30+ min — set the user's expectation up
front), tool installs (~10s for `go install`), and printing-press
subcommands that do network-bound work (crowd-sniff scans npm +
GitHub, ~5-10 min).
Per-violation:
- Lines 262 + 315 ("10-40 minutes depending on API complexity"): bumped
to "30-60 minutes." User feedback: 10-40 min was understated; most
CLIs take 30+ min.
- Line 547 ("Generate a fresh CLI ... ~15-20 min"): dropped. This was
a fabricated sub-task estimate inside an `AskUserQuestion` option.
- Lines 1037 + 1047 (crowd-sniff prompt "typically 2-4 minutes"):
bumped to "5-10 minutes" per user guidance. The 2-4 min figure came
from a March 2026 best-practice doc that was never instrumented;
5-10 min is the realistic post-2026 wall-clock for a typical npm +
GitHub scan.
- Line 1020 (crowd-sniff time budget): bumped from "5 minutes" to
"10 minutes" so the agent-side fallback timeout matches the
user-prompt range. Without this bump the prompt would promise up
to 10 min but the agent would fall back at 5.
- docs/solutions/.../sniff-and-crowd-sniff-complementary-discovery-2026-03-30.md
source-of-truth doc: bumped from 2-4 to 5-10 min for consistency.
Skipped (legitimate, not violations):
- Line 828 references the actual 3-minute budget rule.
- references/setup-checks.md "10 seconds" for `go install` is real
wall-clock, not agent-bound.
- Lines 903-905, 1110, 1128, 1134, 1798: real time budgets enforced
by fallback rules, not user-prompt estimates.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
...f-and-crowd-sniff-complementary-discovery-2026-03-30.md | 2 +-
skills/printing-press/SKILL.md | 14 +++++++-------
2 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/docs/solutions/best-practices/sniff-and-crowd-sniff-complementary-discovery-2026-03-30.md b/docs/solutions/best-practices/sniff-and-crowd-sniff-complementary-discovery-2026-03-30.md
index 5641a6b0..2d1a013f 100644
--- a/docs/solutions/best-practices/sniff-and-crowd-sniff-complementary-discovery-2026-03-30.md
+++ b/docs/solutions/best-practices/sniff-and-crowd-sniff-complementary-discovery-2026-03-30.md
@@ -57,7 +57,7 @@ These are different sets:
**Use crowd-sniff alone** when:
- Browser automation isn't available or is unreliable
- The API requires login (browser-sniff skips auth-required sites)
-- Speed matters (crowd-sniff runs without a browser, typically 2-4 minutes)
+- Speed matters (crowd-sniff runs without a browser, typically 5-10 minutes)
- You want popularity-weighted endpoint coverage
**Use both** when:
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index 0cccd864..26f9592e 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -83,7 +83,7 @@ See the `printing-press-polish` skill for details. It runs diagnostics, fixes ve
- **Do not ship a CLI that hasn't been behaviorally tested against real targets.** `go build` and `verify` pass-rate are structural signals, not correctness signals. Phase 5's mechanical test matrix runs every subcommand + `--json` + error paths; if that matrix was not executed, the CLI is not shippable. Quick Check is the floor; Full Dogfood is required when the user asks for thoroughness.
- **Bugs found during dogfood are fix-before-ship, not "file for v0.2".** If a 1-3 file edit resolves it, do it now. `ship-with-gaps` is deprecated as a default verdict (see Phase 4). Context is freshest in-session; a v0.2 backlog that may never be revisited ships known-broken CLIs.
- **Features approved in Phase 1.5 are shipping scope.** Do not downgrade a shipping-scope feature to a stub mid-build. If implementation becomes infeasible, return to Phase 1.5 with a revised manifest and get explicit re-approval.
-- **Do not quote human-time estimates** ("~15-30 min", "~1 hour", "quick fix") in `AskUserQuestion` options, phase descriptions, or reference docs. Describe scope instead (lines of code, files touched, relative size).
+- **Do not quote human-time estimates for sub-tasks** ("~15-30 min", "~1 hour", "quick fix") in `AskUserQuestion` options, phase descriptions, or reference docs. The agent does the work, not the user; agent-fabricated estimates are notoriously bad and train users to distrust the prompt. Describe scope instead (lines of code, files touched, relative size). The carve-outs are wall-clock estimates for genuinely time-bound things: the whole-CLI run (set the user's expectation up front — most CLIs take 30+ minutes), tool installs (`go install` takes ~10 seconds), and printing-press subcommands that do network-bound work (crowd-sniff scans npm + GitHub, ~5-10 minutes). Anything bounded by agent reasoning time is not time-bound — describe scope.
- Optimize for time-to-ship, not time-to-document.
- Reuse prior research whenever it is already good enough.
- Do not split one idea across multiple mandatory artifacts.
@@ -259,7 +259,7 @@ If the user typed `/printing-press` with no arguments (no API name, no `--spec`,
>
> By the end, you'll have a working CLI in `~/printing-press/library/` that you can use for yourself, ship on your own, or apply to add to the printing-press library.
>
-> The process takes 10-40 minutes depending on API complexity. Simple APIs with official specs (Stripe, GitHub) are faster. Undocumented APIs that need discovery (ESPN, Domino's) take longer.
+> The process takes 30-60 minutes depending on API complexity. Simple APIs with official specs (Stripe, GitHub) are faster. Undocumented APIs that need discovery (ESPN, Domino's) take longer.
Print these example invocations as plain text BEFORE the `AskUserQuestion` call (so they appear as context above the question, not as competing menu options):
@@ -312,7 +312,7 @@ Print as prose, matching the style of the example below:
>
> **What you will have at the end:** A fully functional CLI at `~/printing-press/library/<api>` that you can use yourself, ship on your own, or apply to add to the printing-press library.
>
-> **Time:** 10-40 minutes depending on API complexity.
+> **Time:** 30-60 minutes depending on API complexity.
>
> **Things that help if you have them:**
> - An API key (for live smoke testing at the end)
@@ -544,7 +544,7 @@ Before new research:
If prior research was also found (step 2), include the research summary alongside the library info.
Then ask:
- 1. **"Generate a fresh CLI"** — Re-runs the Printing Press into a working directory, overwrites generated code, then rebuilds transcendence features. Prior research is reused if recent. ~15-20 min.
+ 1. **"Generate a fresh CLI"** — Re-runs the Printing Press into a working directory, overwrites generated code, then rebuilds transcendence features. Prior research is reused if recent.
2. **"Improve existing CLI"** — Keeps all current code, audits for quality gaps, implements top improvements. The Printing Press is not re-run.
3. **"Review prior research first"** — Show the full research brief and absorb manifest before deciding.
@@ -1017,7 +1017,7 @@ Every source named in the briefing must have exactly one entry in `browser-brows
After Phase 1.7 (Browser-Sniff Gate), evaluate whether mining community signals (npm SDKs and GitHub code search) would improve the spec. Skip this gate entirely if the user already passed `--spec` (spec source is already resolved and appears complete).
-**Time budget:** The crowd-sniff gate should complete within 5 minutes. If `printing-press crowd-sniff` fails or times out, fall back immediately:
+**Time budget:** The crowd-sniff gate should complete within 10 minutes. If `printing-press crowd-sniff` fails or times out, fall back immediately:
- If a spec already exists: "Crowd-sniff failed — proceeding with existing spec."
- If no spec exists: "Crowd-sniff failed — falling back to --docs generation."
@@ -1034,7 +1034,7 @@ After Phase 1.7 (Browser-Sniff Gate), evaluate whether mining community signals
Present to the user via `AskUserQuestion`:
-> "Found a spec with **N endpoints**, but research shows the live API likely has more. Want me to search npm packages and GitHub code for `<api>` to discover additional endpoints? This typically takes 2-4 minutes."
+> "Found a spec with **N endpoints**, but research shows the live API likely has more. Want me to search npm packages and GitHub code for `<api>` to discover additional endpoints? This typically takes 5-10 minutes."
>
> Options:
> 1. **Yes — crowd-sniff and merge** (search npm SDKs and GitHub code, merge discovered endpoints with the existing spec)
@@ -1044,7 +1044,7 @@ Present to the user via `AskUserQuestion`:
Present to the user via `AskUserQuestion`:
-> "No OpenAPI spec found for `<API>`. Want me to search npm packages and GitHub code to discover the API from community usage? This typically takes 2-4 minutes."
+> "No OpenAPI spec found for `<API>`. Want me to search npm packages and GitHub code to discover the API from community usage? This typically takes 5-10 minutes."
>
> Options:
> 1. **Yes — crowd-sniff the community** (search npm SDKs and GitHub code, generate a spec from discovered endpoints)
← 00f83219 fix(skills): add Phase 3 starter templates for novel feature
·
back to Cli Printing Press
·
docs(cli): document OpenAPI extensions and link it from AGEN 5920d005 →