staruhub/ClaudeSkills / skills/Geek-skills-product-manager
product-manager
Verified资深产品经理助手,提供 PRD/MRD/BRD 创作与评审、产品策略、留存增长、竞品分析、功能优先级,以及 grill-me-to-doc 逐轮访谈。用户要求“逐个问我”“先把需求问清楚”“grill me”“把想法变成产品文档”时进入 grill-me-to-doc:先读仓库证据,每轮只问一个决策,给推荐答案与理由,记录决策和未决项,支持 resume,产出结构化 PRODUCT-DOC;文档完成且用户批准前硬停止,任何时候都不写实现代码。即使未提“产品”,讨论 App 功能、增长或商业模式也应触发。不用于:单纯代码实现、系统架构深设(用 solution-architect)、需多源引用的市场调研(用 deep-research)、纯营销文案。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.4 KB |
| evals/routing-evals.json | config | 2.1 KB |
| references/GRILL-ME-TO-DOC.md | markdown | 6.0 KB |
| references/PM-BEST-PRACTICES.md | markdown | 16.7 KB |
| references/PRD-TEMPLATE.md | markdown | 11.6 KB |
| references/PRD-WRITING-GUIDE.md | markdown | 13.0 KB |
| references/PRODUCT-DOC-TEMPLATE.md | markdown | 1.6 KB |
| references/REVIEW-CHECKLIST.md | markdown | 12.8 KB |
| schemas/grill-state.schema.json | config | 5.0 KB |
| scripts/validate_grill_session.py | script | 12.3 KB |
scripts/validate_grill_session.py
View on GitHub#!/usr/bin/env python3
"""Validate a grill-me-to-doc state, transcript, and PRODUCT-DOC.
The validator uses only the Python standard library and fails closed: any
contract error exits 1.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import re
import sys
from pathlib import Path
from typing import Any
GATE_KEYS = {
"problem",
"users_jtbd",
"evidence_assumptions",
"scope_non_goals",
"flows",
"requirements",
"success_metrics",
"risks",
"open_questions",
"acceptance_criteria",
}
DOC_HEADINGS = [
"## 1. Problem and desired outcome",
"## 2. Primary users and JTBD",
"## 3. Evidence and assumptions",
"## 4. Scope and non-goals",
"## 5. User flow and failure recovery",
"## 6. Requirements",
"## 7. Success metrics and guardrails",
"## 8. Risks and dependencies",
"## 9. Open questions",
"## 10. Acceptance criteria",
"## Decision log",
"## Implementation boundary",
]
FORBIDDEN_ACTIONS = {
"write_code",
"create_scaffold",
"create_branch",
"commit",
"push",
"implement",
"create_ticket",
}
def canonical_utf8_lf(data: bytes) -> bytes:
"""Return UTF-8 text with CRLF/CR normalized to LF and no other changes."""
text = data.decode("utf-8")
return text.replace("\r\n", "\n").replace("\r", "\n").encode("utf-8")
def canonical_text_sha256(data: bytes) -> str:
return hashlib.sha256(canonical_utf8_lf(data)).hexdigest()
def load_json(path: Path) -> Any:
try:
return json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
raise ValueError(f"{path}: cannot parse JSON: {exc}") from exc
def question_count(text: str) -> int:
return len(re.findall(r"[??]", text))
def validate_state(state: dict[str, Any], errors: list[str]) -> None:
required = {
"schema_version",
"session_id",
"skill_version",
"mode",
"status",
"evidence",
"decision_log",
"unresolved_questions",
"completion_gate",
"product_doc",
"hard_stop",
}
missing = required - state.keys()
if missing:
errors.append(f"state missing keys: {sorted(missing)}")
return
if state["schema_version"] != "1.0.0":
errors.append("state schema_version must be 1.0.0")
if state["skill_version"] != "1.2.0":
errors.append("state skill_version must be 1.2.0")
if state["mode"] != "grill-me-to-doc":
errors.append("state mode must be grill-me-to-doc")
evidence = state["evidence"]
if not isinstance(evidence, list) or not evidence:
errors.append("state must contain at least one evidence entry")
else:
for index, item in enumerate(evidence):
if not isinstance(item, dict):
errors.append(f"evidence[{index}] must be an object")
continue
if not re.fullmatch(r"[a-f0-9]{64}", str(item.get("sha256", ""))):
errors.append(f"evidence[{index}] has invalid sha256")
if not item.get("path") or not item.get("summary"):
errors.append(f"evidence[{index}] needs path and summary")
decisions = state["decision_log"]
decision_ids = [item.get("id") for item in decisions if isinstance(item, dict)]
if len(decision_ids) != len(set(decision_ids)):
errors.append("decision_log ids must be unique")
unresolved = state["unresolved_questions"]
unresolved_ids = [item.get("id") for item in unresolved if isinstance(item, dict)]
if len(unresolved_ids) != len(set(unresolved_ids)):
errors.append("unresolved question ids must be unique")
gate = state["completion_gate"]
if not isinstance(gate, dict) or set(gate) != GATE_KEYS:
errors.append(f"completion_gate keys must equal {sorted(GATE_KEYS)}")
elif state["status"] in {"ready-for-draft", "awaiting-approval", "approved", "stopped"}:
if not all(value is True for value in gate.values()):
errors.append(f"status {state['status']} requires every completion gate to be true")
hard_stop = state["hard_stop"]
if not isinstance(hard_stop, dict) or hard_stop.get("implementation_allowed") is not False:
errors.append("hard_stop.implementation_allowed must be false")
product_doc = state["product_doc"]
if state["status"] in {"approved", "stopped"}:
if product_doc.get("approved_by_user") is not True:
errors.append("approved/stopped state requires explicit user approval")
if not product_doc.get("final_path"):
errors.append("approved/stopped state requires final_path")
def validate_transcript(
state: dict[str, Any],
transcript: dict[str, Any],
transcript_dir: Path,
errors: list[str],
) -> None:
events = transcript.get("events")
if transcript.get("schema_version") != "1.0.0":
errors.append("transcript schema_version must be 1.0.0")
if transcript.get("session_id") != state.get("session_id"):
errors.append("transcript session_id does not match state")
if not isinstance(events, list) or not events:
errors.append("transcript events must be a non-empty array")
return
expected_seq = list(range(1, len(events) + 1))
actual_seq = [event.get("seq") for event in events if isinstance(event, dict)]
if actual_seq != expected_seq:
errors.append("transcript seq values must be contiguous from 1")
seen_questions: dict[str, int] = {}
answered: set[str] = set()
first_question_seq: int | None = None
draft_seq: int | None = None
approval_seq: int | None = None
resume_expected: str | None = None
for event in events:
if not isinstance(event, dict):
errors.append("every transcript event must be an object")
continue
actor = event.get("actor")
kind = event.get("kind")
seq = event.get("seq")
if kind == "question":
first_question_seq = first_question_seq or seq
qid = event.get("question_id")
question = str(event.get("question", ""))
recommendation = event.get("recommendation", {})
if not qid or qid in seen_questions:
errors.append(f"event {seq}: question_id missing or reused")
else:
seen_questions[qid] = seq
if question_count(question) != 1:
errors.append(f"event {seq}: question turn must contain exactly one question mark")
if not recommendation.get("answer") or not recommendation.get("reason"):
errors.append(f"event {seq}: recommendation needs answer and reason")
if not event.get("evidence"):
errors.append(f"event {seq}: question needs evidence context")
if resume_expected and qid != resume_expected:
errors.append(
f"event {seq}: resume expected {resume_expected}, got {qid}"
)
resume_expected = None
elif kind == "answer":
qid = event.get("question_id")
if actor != "user" or qid not in seen_questions:
errors.append(f"event {seq}: answer must match an earlier question")
else:
answered.add(qid)
elif kind == "resume":
if actor != "assistant":
errors.append(f"event {seq}: resume must be an assistant event")
resume_expected = event.get("from_next_question_id")
state_path = event.get("state_path")
state_sha = event.get("state_sha256")
if not resume_expected or not state_sha or not state_path:
errors.append(f"event {seq}: resume needs state path, hash, and next question id")
else:
try:
resume_bytes = (transcript_dir / state_path).read_bytes()
canonical_state = canonical_utf8_lf(resume_bytes)
actual_sha = hashlib.sha256(canonical_state).hexdigest()
if actual_sha != state_sha:
errors.append(f"event {seq}: resume state hash mismatch")
resume_state = json.loads(canonical_state.decode("utf-8"))
if resume_state.get("session_id") != state.get("session_id"):
errors.append(f"event {seq}: resume state session_id mismatch")
if resume_state.get("next_question_id") != resume_expected:
errors.append(f"event {seq}: resume next question mismatch")
except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
errors.append(f"event {seq}: cannot load resume state: {exc}")
elif kind == "document_draft":
draft_seq = seq
if event.get("gate_passed") is not True:
errors.append(f"event {seq}: draft emitted before completion gate")
if question_count(str(event.get("question", ""))) != 1:
errors.append(f"event {seq}: approval turn must ask exactly one question")
recommendation = event.get("recommendation", {})
if not recommendation.get("answer") or not recommendation.get("reason"):
errors.append(f"event {seq}: approval turn needs recommendation and reason")
elif kind == "approval":
if actor != "user" or event.get("approved") is not True:
errors.append(f"event {seq}: approval must be explicit and from user")
approval_seq = seq
elif kind == "final":
if not approval_seq or approval_seq >= seq:
errors.append(f"event {seq}: final document requires earlier approval")
actions = set(event.get("actions", []))
forbidden = sorted(actions & FORBIDDEN_ACTIONS)
if forbidden:
errors.append(f"event {seq}: forbidden implementation actions {forbidden}")
if event.get("implementation_started") is not False:
errors.append(f"event {seq}: implementation_started must be false")
if first_question_seq:
prior_evidence = [
e for e in events
if e.get("seq", 0) < first_question_seq and e.get("kind") == "evidence_read"
]
if not prior_evidence:
errors.append("repository evidence must be read before the first question")
if draft_seq and (not approval_seq or approval_seq <= draft_seq):
errors.append("explicit approval must follow the document draft")
if resume_expected:
errors.append("resume event was not followed by its stored next question")
logged_question_ids = {
item.get("question_id")
for item in state.get("decision_log", [])
if item.get("question_id")
}
missing_logs = answered - logged_question_ids
if missing_logs:
errors.append(f"answered questions missing from decision log: {sorted(missing_logs)}")
def validate_doc(state: dict[str, Any], text: str, errors: list[str]) -> None:
if state.get("status") not in {"approved", "stopped"}:
return
for heading in DOC_HEADINGS:
if heading not in text:
errors.append(f"PRODUCT-DOC missing heading: {heading}")
if re.search(r"\bTBD\b|待补充|此处略|placeholder", text, flags=re.IGNORECASE):
errors.append("PRODUCT-DOC contains placeholder text")
if "Approved by user: true" not in text:
errors.append("PRODUCT-DOC must record explicit approval")
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--state", required=True, type=Path)
parser.add_argument("--transcript", required=True, type=Path)
parser.add_argument("--product-doc", required=True, type=Path)
args = parser.parse_args()
errors: list[str] = []
try:
state = load_json(args.state)
transcript = load_json(args.transcript)
doc = args.product_doc.read_text(encoding="utf-8")
validate_state(state, errors)
validate_transcript(state, transcript, args.transcript.parent, errors)
validate_doc(state, doc, errors)
except (OSError, ValueError) as exc:
errors.append(str(exc))
if errors:
for error in errors:
print(f"ERROR {error}")
print(f"FAIL {len(errors)} error(s)")
return 1
print("PASS grill-me-to-doc contract")
return 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |