sno-ai/sno-station-skills / plugins/sno-station-standalone/skills/first-principles-review
first-principles-review
VerifiedMANUAL-ONLY: challenge a product idea, design, PRD, or architecture from first principles. Use only when the user names this skill. Research first, then write a local review and PRD handoff.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| agents/openai.yaml | config | 353 B |
| references/report-contract.md | markdown | 3.2 KB |
| scripts/extract-prd-handoff.pyexecutable | script | 1.1 KB |
| scripts/selftest/fixtures/expected-handoff.json | config | 1.9 KB |
| scripts/selftest/fixtures/scenarios/inherited-constraint-test-first.md | markdown | 2.1 KB |
| scripts/selftest/fixtures/scenarios/raw-idea-reframe.md | markdown | 2.1 KB |
| scripts/selftest/fixtures/scenarios/sound-design-proceed.md | markdown | 2.0 KB |
| scripts/selftest/fixtures/target-prd.md | markdown | 347 B |
| scripts/selftest/fixtures/valid-report.md | markdown | 3.9 KB |
| scripts/selftest/run-extractor-test.shexecutable | script | 1.9 KB |
| scripts/selftest/run-scenarios.shexecutable | script | 3.2 KB |
| scripts/selftest/run-selftest.shexecutable | script | 4.9 KB |
| scripts/selftest/verify-manual-only.shexecutable | script | 2.8 KB |
| scripts/selftest/verify-workflow-policy.shexecutable | script | 1.8 KB |
| scripts/validate-report.pyexecutable | script | 9.6 KB |
scripts/selftest/run-selftest.sh
View on GitHub#!/usr/bin/env bash
set -u -o pipefail
export PYTHONDONTWRITEBYTECODE=1
selftest_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
skill_dir="$(cd "$selftest_dir/../.." && pwd)"
fixtures="$selftest_dir/fixtures"
source_skill="$skill_dir/SKILL.md"
codex_metadata="$skill_dir/agents/openai.yaml"
validator="$skill_dir/scripts/validate-report.py"
extractor="$skill_dir/scripts/extract-prd-handoff.py"
failures=0
fail() { echo "FAIL: $*" >&2; failures=$((failures + 1)); }
require_file() { [[ -f "$1" ]] || fail "missing required file: $1"; }
expect_success() {
local label="$1"
shift
if ! "$@"; then
fail "$label should succeed"
fi
}
expect_failure() {
local label="$1"
shift
if "$@"; then
fail "$label should be rejected"
fi
}
require_file "$source_skill"
require_file "$codex_metadata"
require_file "$validator"
require_file "$extractor"
if [[ -f "$source_skill" ]]; then
grep -Fq "MANUAL-ONLY" "$source_skill" || fail "skill description must say MANUAL-ONLY"
if grep -Eiq "placeholder|todo:.*implement|coming soon" "$source_skill"; then
fail "skill source still contains a placeholder"
fi
fi
if [[ -f "$codex_metadata" ]]; then
grep -Eq 'allow_implicit_invocation:[[:space:]]*false' "$codex_metadata" || \
fail "Codex metadata must disable implicit invocation"
fi
if [[ -f "$validator" && -f "$extractor" ]]; then
temporary="$(mktemp -d)"
trap 'rm -rf "$temporary"' EXIT
expect_success "conforming report" python3 "$validator" "$fixtures/valid-report.md"
python3 - "$fixtures/valid-report.md" "$temporary" <<'PY'
import pathlib
import sys
source = pathlib.Path(sys.argv[1]).read_text(encoding="utf-8")
output = pathlib.Path(sys.argv[2])
def write(name, text):
(output / name).write_text(text, encoding="utf-8")
write("missing-section.md", source.replace("## Falsifiers\n\n", ""))
write("unknown-disposition.md", source.replace("REFRAME", "APPROVE"))
write("empty-research.md", source.replace('"research_receipt":[{', '"research_receipt":[] , "discarded": [{'))
write("unresolved-recommendation.md", source.replace('"recommendation":"Use priority-based delivery before building a queue."', '"recommendation":""'))
write("malformed-json.md", source.replace('{"true_problem"', '{"true_problem":,'))
write("question-in-report.md", source.replace("high priority.\n\n## PRD Handoff", "high priority?\n\n## PRD Handoff"))
write("accept-url-with-query.txt", source.replace("high priority.\n\n## PRD Handoff", "high priority. See https://example.com/doc?page=2 for detail.\n\n## PRD Handoff"))
write("zero-handoff.md", source.replace('{"true_problem"', '{}\n<!-- discarded {"true_problem"'))
write("zero-work.md", source.replace("| `fixtures/target-prd.md:1-12` | The proposal assumes a queue and a universal ten-second target. | verified |", "No research was performed.").replace("| Ten seconds is required for every event | unproven | inversion | falsified for low-priority events |", "No premises were challenged."))
write("empty-premises.md", source.replace('"premises":[{', '"premises":[],"discarded":[{', 1))
write("split-empty-outcomes.md", source.replace('"disposition":"REFRAME"', '"disposition":"SPLIT"', 1))
write("split-one-outcome.md", source.replace('"disposition":"REFRAME"', '"disposition":"SPLIT"', 1).replace('"split_outcomes":[]', '"split_outcomes":["Only one outcome"]', 1))
write("non-split-outcomes.md", source.replace('"split_outcomes":[]', '"split_outcomes":["Unexpected split outcome"]', 1))
write("multiple-handoff.md", source + "\n```json\n{}\n```\n")
PY
expect_success "URL with query string" python3 "$validator" "$temporary/accept-url-with-query.txt"
for report in "$temporary"/*.md; do
expect_failure "$(basename "$report")" python3 "$validator" "$report"
done
expect_success "scenario reports" bash "$selftest_dir/run-scenarios.sh"
extracted="$temporary/extracted.json"
if python3 "$extractor" "$fixtures/valid-report.md" >"$extracted"; then
if ! python3 - "$fixtures/expected-handoff.json" "$extracted" <<'PY'
import json
import pathlib
import sys
expected = json.loads(pathlib.Path(sys.argv[1]).read_text(encoding="utf-8"))
observed = json.loads(pathlib.Path(sys.argv[2]).read_text(encoding="utf-8"))
if observed != expected:
raise SystemExit("extracted JSON differs from the embedded handoff")
PY
then
fail "extractor must emit exactly the embedded handoff JSON"
fi
else
fail "extractor should accept the conforming report"
fi
expect_failure "extractor malformed JSON" python3 "$extractor" "$temporary/malformed-json.md"
expect_failure "extractor multiple handoff blocks" python3 "$extractor" "$temporary/multiple-handoff.md"
fi
for verifier in verify-workflow-policy.sh verify-manual-only.sh run-extractor-test.sh; do
if ! output="$(bash "$selftest_dir/$verifier" 2>&1)"; then
printf '%s\n' "$output" >&2
fail "$verifier failed"
fi
done
if (( failures > 0 )); then
echo "self-test failed with $failures failure(s)" >&2
exit 1
fi
echo "self-test passed"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |