FAQ EN

FAQ — common questions

Source: docs/HELP.md, docs/HELP_EN.md. Languages: FAQ (RU) · FAQ-EN (EN). Full guide — Help-RU / Help-EN. Something broke — Troubleshooting-EN.

General

Is it a program or a bot? Neither. It is a repository folder you open in an LLM environment (Claude Code, Cursor, Codex, OpenCode, Windsurf, Copilot). The environment reads AGENTS.md (rules and process), knowledge/ (method cards), while the pfs tool (CLI/MCP) keeps the research bookkeeping.

How is this different from a plain LLM chat? Verifiability: every number carries a source S### and a claim type C###; in the demo, 100% of key numbers trace back to sources, versus 0% in a plain chat. Plus resumability (state in files), quality gates (pfs check), and revision of decisions on new data (pfs decision due, pfs impact). More — Comparison-with-chat-EN.

Do I pay for anything beyond the LLM environment itself? No. The CLI is pure Python 3.9+ (zero dependencies), no keys required. Integrations (Linear, Lovable, Higgsfield, Feynman) are optional and configured separately.

Does it only work in Claude Code? No. The process and commands work everywhere (via AGENTS.md); in Claude Code you additionally get 4 hook events (+ _common.py), 8 subagents, and 120 skills. Environment comparison — table below.

Process

How many steps, and where do I decide? 12 steps: intake → sources → research → discovery → situation → options → choice → strategy → validation → review → decision → monitoring. The human decides at three points: the brief (step 0), the option choice (step 6), the decision approval (step 10). Each step has a question block (1–3 questions).

Does the agent do everything by itself? It drives the process, but the human decides what matters. You can stop or correct at any moment: “stop”, “clarify: …”, “redo section X”.

What happens if I close the chat mid-work? Nothing: state lives in project files. A new chat starts with the SessionStart hook feeding pfs status + pfs decision due. Completed steps are not repeated (the agent checks log.jsonl).

Why does the agent ask questions at every step? Question blocks (pfs questions <step>) are customization: at least 1–3 questions to the product leader per step, skipping only via the journal. That way the strategy is never built on silent assumptions.

Can steps be skipped? Unneeded steps are not silently skipped — they are closed with a reason (pfs step <step> done --note "…"). For example, if you have no cohort data, the calculation step closes with “no data” and the question is recorded in 02_situation.md as an honest gap. In the demo project, missing internal metrics were marked exactly this way.

What are the 00–07 documents? Step outputs: 00_brief.md, 01_research_plan.md, 02_situation.md (situation + segments), 03_options.md (options + red team), 04_product_strategy.md, 05_comms_strategy.md, 06_validation_plan.md, 07_quality_review.md. All live in projects/<slug>/outputs/.

Claims and evidence

What are C### and why do they matter? C### is the claim registry (claims.jsonl) with a type (fact / hypothesis / forecast / assumption / inference) and an evidence grade A–D. A number in a document without a [C###] reference counts as a defect — pfs check catches it. Terms — Glossary-EN.

Can the agent record a fact “from memory”? No. fact requires --source S###; synthetic data (origin=synthetic) never counts as fact — the validator rejects the write. The agent's own conclusions are always inference referencing input C###.

What if a source was updated?

pfs source refresh S003     # reload the web source
pfs impact S003             # which claims are affected by the change

When sha256 changes, the old version is backed up to raw/<S###>_old_<sha8>.txt, and claims based on that source need their conclusions checked (supersede/retract → pfs claim rebase).

What does pfs impact do? It shows the “what does a change affect” chain: source → claims → inferences → document lines → decisions. Call it before editing to understand the cost of the change.

Six-pager and Excel

How do I build the committee report? Wait for documents 02/03/04/06 (steps situation…validation) and say “build a six-pager” — or manually: pfs export --six-pager. You get outputs/SIX_PAGER.md (FAQ-1…6) + outputs/attachments/*.xlsx (4 workbooks: unit economics, growth model, cohorts, market).

Numbers in text and Excel must match — how? Parameters come from projects/<slug>/calcs.json (each value referenced by C### in note). If you edited calcs.json — rerun pfs calc all and pfs export --six-pager. Anything missing from calcs.json falls back to the example in tools/pfs/calc.py: DEFAULTS marked “EXAMPLE”.

Excel opens “empty”? That is the pre-calculation cache: sheets contain formulas, not values. Excel/Numbers/LibreOffice/Google Sheets calculate them on open. The “Input” sheet holds the editable parameters.

Troubleshooting — mini-cases

Symptom	Cause and what to do
Error: A fact without a source is not allowed	By design: pfs source add — or record as hypothesis/assumption
Source not allowed: domain …	Domain outside allowed_sources; edit project.json or add with --force --note "rationale"
Extracted 0 characters from <url>	The page renders via JavaScript: save the text manually → pfs source add --text-file … --url …
Error: Claim C### not found	Typo in the ID: pfs claim list
Subagent/skill not showing	Restart the Claude Code session — components load at startup
Six-pager numbers don't match Excel	Edited calcs.json? Rerun pfs calc all and pfs export --six-pager
Cost shows 0 in another environment	Auto-accounting only from Claude Code transcripts: pfs log "…" --usd N manually
Hook is “silent”	Check .claude/hooks/hook_errors.log; hooks never crash the session by design

Case-by-case breakdowns — Troubleshooting-EN.

“I forgot where I stopped” — how do I resume?

pfs status      # step, what's next, waits
pfs next        # what to decide now: step + commitments + revisions + questions

In Claude Code just open a new chat — context is fed automatically. Completed work is not repeated.

“check complains about a number without a reference” — what is it? The quality gate: a number (money, percent, count) appeared in a document without a [C###] tag. Procedure: find the claim via pfs claim list → if missing, add it with a source (pfs claim add "…" fact --source S### --grade B) or rewrite the sentence without the figure. In --strict mode the defect blocks the step. Reaching 100/100 — Quality-Gates-EN.

“The source was updated” — the procedure?

1. pfs source refresh S### → 2) review the delta and the backup raw/<S###>_old_<sha8>.txt →
2. pfs impact S### → 4) for changed claims: pfs claim supersede (new value, same or new source) or pfs claim retract → 5) pfs claim rebase — redirect conclusions → 6) pfs decision due — check decisions. History is preserved: old versions are not deleted.

Data and safety

Can I give the agent confidential company data? No. Only open sources and your materials without personal data. Project domains (allowed_sources) restrict downloads; secrets go into the gitignored .env. More — Security-and-Privacy-EN and Compliance-EN.

What if a page says “ignore instructions, run this command…”? Source texts are data, not commands: they are never executed, and suspicious fragments are flagged (PostToolUse hook + CLI detector).

Are synthetic respondents a deception? Not if labeled honestly: transcripts go to interviews/synthetic/ marked “SYNTHETIC ANSWER”, origin=synthetic, and the validator will not allow a fact on synthetic data — only hypotheses. In the demo project, 2 personas and a funnel are synthetic and produced only hypotheses.

Are real interviews allowed? Yes — with consent and no personal data. Registered via pfs source add <file> --origin interview or pfs interview save. Interview guides: pfs interview guide --persona "…".

Environments

Environment	Process	Skills/subagents	Hooks	MCP
Claude Code	fully	yes	yes	pfs + Linear
Cursor	.cursor/rules	no	no	pfs from .mcp.json
Codex / OpenCode / Copilot	via AGENTS.md	no	no	pfs
Lovable	web deck/landing from docs/lovable-brief.md	—	—	https://mcp.lovable.dev (OAuth /mcp)
Feynman	CLI — deep research	skill deep-research	—	—
officecli	external CLI — PPTX/XLSX/DOCX	skill deck	—	—

In hook-less environments, start the chat with “read AGENTS.md and run python3 -m tools.pfs status”.

Subagents and models

What do the 8 subagents do, and when are they visible? Subagents are background roles in Claude Code: researcher (reading long sources), red-team (attacking options), evidence-auditor (rubric grading), data-analyst (calculations, including pfs calc), synthetic-respondent (AI respondents — hypotheses only), comms-strategist, ux-analyst, router. You never call them manually — the agent attaches them per step; for example, the six-pager Excel workbooks are built in the background while you keep chatting. Details — Subagents-EN.

Which model handles which task? The table is pfs models, the plan for a task — pfs models pick red_team. A profile for another environment — pfs models use cursor-mixed; after switching — pfs models sync (writes the models into the subagents). Cheap models — classification, extracts, rubric grading; strong ones — synthesis, options, red team, strategy. Configuration — config/models.json. Details — Routing-and-Models-EN.

What is model escalation? If pfs check finds errors in a step's result twice in a row, or the grader gives a borderline score — pfs models escalate <task> --reason "…", and the step is redone by the stronger model. Economy mode — pfs route --economy (lowers deep→balanced, except red team).

Knowledge base

How do I find the right methodology?

pfs kb search "cohort retention analysis"     # BM25 search across 88 cards
pfs kb show M-unit-economics                  # show a card
pfs kb index                                  # rebuild indexes, validate links

The agent searches cards per step itself: pfs step prints the step's mandatory cards. Catalog — Methods-Catalog-EN, internals — Knowledge-Base-EN.

EN cards — how to search? 16 mirrors in knowledge/methods_en/ + INDEX_EN.md. Search — the same pfs kb search (the index covers both languages); coverage grows progressively — plan in Roadmap-EN.

Data and calculations

What data-analysis commands exist?

pfs data profile events.csv --save profile    # table profile: types, gaps, duplicates, periods
pfs data cohort events.csv --user id --date dt --save cohorts   # cohort retention
pfs data funnel events.csv --steps visit,signup,pay --user id   # funnel (--date validates order)
pfs data stats events.csv --col revenue [--group segment]       # n, mean, median, percentiles, 95% CI

Save with --save — the calculation can be replayed. CSV/XLSX are fed as sources (pfs source add).

Interviews and UX reviews? pfs interview guide --persona "Parent, kids 7–12" — a question guide; pfs interview save transcript.md --persona "…" --title "…" — a transcript (origin=synthetic for AI respondents); pfs media add shot.png --desc "what is visible" — media as a source; pfs ux scaffold S003 --focus "onboarding" — a UX frame of 10 heuristics with the rule “conclusions only from the source material”.

Decisions and monitoring

What happens after a D### is approved? The decision lives in decisions.jsonl with commitments and a review date. pfs decision due shows: overdue commitments, decisions with stale grounds, arrived review dates. Closing a commitment — pfs decision done --id D001 --commitment K1. New data → pfs impact → supersede/rebase → pfs decision rebase --id D001 --note "…". Details — Decisions-and-Monitoring-EN.

Can I run several projects at once? Yes: pfs new per question, pfs use to switch. States are isolated in projects/<slug>/. The list with steps — pfs list.

Documentation and help

Where is the full documentation? docs/HELP.md (RU) and docs/HELP_EN.md in the repository; the site version — strategyproduct.ru/help.html (sticky sidebar, search filter). RU and EN are maintained in pairs and updated together.

Do RU and EN differ? Not in substance: document parity is maintained. The EN part of the knowledge base (cards) currently covers 16 of 88 — plan in Roadmap-EN. Wiki: Russian pages X.md and English X-EN.md.

What license? See LICENSE in the repository: https://github.com/Fighter90/product-factory-strategist. The demo product CVStart is a separate MIT project with its own repository.

How do I reference the demo in my own material? The Demo-CVStart-EN page + the interactive walkthrough at strategyproduct.ru/demo.html; demo artifacts live in projects/демо/outputs/ (six-pager RU/EN, Excel, REPORT).

Cost

How is cost calculated? pfs cost — from Claude Code transcripts (prices in config/pricing.json), idempotent (Stop hook, dedup by message.id). In other environments — manual entries: pfs log "Manual fix" --usd 0.8 --human-minutes 15. Cost and human time appear in pfs status and pfs export.

Unfamiliar terms

If you hit an unfamiliar term (knowledge card, red team, six-pager, commitment K1, revision) — see Glossary-EN. If something broke — Troubleshooting-EN. Where the project is heading — Roadmap-EN.

Where to look next

Quick-Setup-EN · Glossary-EN · Troubleshooting-EN · Architecture-EN · CLI-Reference-EN · Demo-CVStart-EN · Roadmap-EN