Troubleshooting

Troubleshooting — симптом → причина → решение

Языки: Troubleshooting (RU) · Troubleshooting-EN (EN). Быстрая диагностика: pfs doctor · pfs status · pfs next. Родственные страницы: FAQ · Glossary · CLI-Reference.

Как диагностировать

python3 -m tools.pfs doctor      # окружение: Python, PDF-инструменты, база знаний, активный проект
python3 -m tools.pfs status      # активный проект, шаг, ожидания, стоимость
python3 -m tools.pfs next        # что решать сейчас: шаг, обязательства, пересмотры, вопросы
python3 -m tools.pfs log         # журнал действий проекта
cat .claude/hooks/hook_errors.log  # ошибки хуков (хуки не роняют сессию — пишут сюда)

Проекты и состояние

Симптом	Причина	Решение
pfs status говорит «проект не выбран»	активный проект не установлен	pfs list → pfs use <slug>; новый — pfs new "Название" "Запрос"
pfs use <slug> не находит проект	опечатка в slug или проект в другом клоне репозитория	скопируйте slug из pfs list дословно (кириллица чувствительна к регистру)
Новый чат «ничего не знает»	среда без хуков (Cursor/Codex/OpenCode)	начните чат с «прочитай AGENTS.md и python3 -m tools.pfs status»
Агент повторяет уже сделанные шаги	проект не выбран или журнал пуст	проверьте pfs status; журнал — projects/<slug>/log.jsonl
Забыл, где остановился	—	pfs next: текущий шаг + просроченные обязательства + пересмотры + открытые вопросы
Стоимость считается = 0	автоучёт только по транскриптам Claude Code	в другой среде: pfs log "…" --usd 0.8 --human-minutes 15

Источники (S###)

Симптом	Причина	Решение
Источник не разрешён: домен …	домен вне allowed_sources проекта	добавьте домен в projects/<slug>/project.json или pfs source add <url> --force --note "обоснование"
Из <url> извлечено 0 знаков	страница рендерится JavaScript	сохраните текст вручную → pfs source add --text-file file.md --url <url> --title "…"
Секретный файл добавляется как источник	защита сработала (.ssh, ключи, .env)	так и задумано; подавайте материалы без секретов
source add вернул существующий S###	дедуп по URL/SHA-256 — это тот же материал	это не ошибка: используйте возвращённый ID; если нужно обновить — pfs source refresh S###
PDF не парсится	нет pdftotext (poppler) или pypdf	brew install poppler / pip install pypdf, проверка — pfs doctor
Веб-источник изменился на сервере	содержимое по URL обновилось	pfs source refresh S### → бэкап в raw/<S###>_old_<sha8>.txt → pfs impact S### → supersede/rebase
Хочу снять текст с JS-страницы конкурента	обычный WebFetch не рендерит JS	skill deep-research (Feynman) или reverse-engineering (rea), затем --text-file

Утверждения (C###) и pfs check

Симптом	Причина	Решение
Ошибка: Факт без источника недопустим	fact требует --source S###	добавьте источник или смените тип на hypothesis/assumption
Ошибка: Утверждение C### не найдено	опечатка в ID	pfs claim list — сверяйте ID
Валидатор отклонил факт на синтетике	origin=synthetic — только гипотезы	так и задумано; запишите как hypothesis
check ругается: число без тега	в документе число (деньги/проценты) без [C###]	найдите утверждение (pfs claim list) → добавьте тег или запишите C###; см. Quality-Gates
check --strict блокирует шаг	дефекты в --strict режиме — стоп-ворота	исправьте по списку pfs check --json; в демо — 100/100 как ориентир
Утверждение устарело	новые данные противоречат C###	pfs claim supersede --id C### "новое" --reason "…" --source S###; история сохраняется
Утверждение было ошибкой	методика/источник неверны	pfs claim retract --id C### --reason "…"
Выводы ссылаются на замещённое утверждение	supersede/retract оторвал основания	pfs claim rebase (все) или --id C### (одно); отозванные — пересмотреть по существу
Хочу знать цену изменения	—	`pfs impact S###

Excel, six-pager и отчёты

Симптом	Причина	Решение
Excel открывается «пустым»	листы содержат формулы, не значения — кэш до пересчёта	откройте в Excel/Numbers/LibreOffice/Google Sheets — посчитается при открытии; лист «Ввод» — параметры
Числа six-pager ≠ Excel	правили calcs.json после сборки	pfs calc all → pfs export --six-pager; в calcs.json каждое значение с C### в note
В Excel фигурирует «ПРИМЕР»	значения не заданы в calcs.json	подставьте фактические значения с C###; дефолты из tools/pfs/calc.py: DEFAULTS
pfs export --six-pager долго собирает книги	Excel-генерация вычислений	это фоновая задача субагента; можно продолжать диалог
DOCX без картинок/форматирования	pfs docx — конвертер без зависимостей	для сложной вёрстки — officecli (PPTX/XLSX/DOCX); простые документы остаются в pfs docx

Хуки и MCP

Симптом	Причина	Решение
Хук «молчит» / не сработал	исключение в скрипте или нет активного проекта	.claude/hooks/hook_errors.log; pfs status; хуки не роняют сессию по дизайну
WebFetch заблокирован хуком	домен вне allowed_sources	это PreToolUse до запроса; добавьте домен в project.json
MCP pfs-strategist недоступен	не настроен .mcp.json или сервер не поднят	перезапустите среду; CLI-эквивалент работает всегда: python3 -m tools.pfs …
Linear/Lovable MCP не отвечает	ключ/OAuth не настроены	LINEAR_API_KEY в .env; Lovable — OAuth /mcp → Authenticate; интеграции опциональны
Стоимость в pfs status не обновляется	хук Stop считает идемпотентно по транскриптам	норма в других средах; ручная запись — pfs log "…" --usd N

Среда и компоненты

Симптом	Причина	Решение
Субагент/скилл не появился	компоненты подхватываются при старте сессии	перезапустите сессию Claude Code
ModuleNotFoundError: tools	вы не в корне репозитория	cd в папку клона
Тесты падают пачкой	не тот Python или повреждён клон	python3 --version (нужно 3.9+); пересоздайте клон; 103 теста должны быть зелёными
Модель ведёт себя не по процессу	в среде не прочитан AGENTS.md	начните чат с «прочитай AGENTS.md и pfs status»; модели под задачи — pfs models
Навык конфликтует с методикой	приоритет у knowledge/	так и задумано: методология приоритетнее процедуры навыка

GitHub Pages и вики

Симптом	Причина	Решение
Сайт strategyproduct.ru показывает старую версию	кэш Pages/CDN	hard-reload (Ctrl/Cmd+Shift+R); Pages пересобирается после пуша — подождите минуту
Вики-ссылка ведёт на несуществующую страницу	страница не создана или имя с опечаткой	проверьте имя по карте вики: Home; RU/EN пары: X.md + X-EN.md
Сайдбар вики не обновился	кэш _Sidebar.md	откройте любую страницу заново; кэш браузера — hard-reload

Командные связки для диагностики

Типовые последовательности вместо разрозненных команд:

«Что-то не так, но что — непонятно»

pfs doctor && pfs status && pfs check --strict

«Проверить цепочку доказательности проекта»

pfs source list && pfs claim list && pfs impact C001

«Пересобрать отчёт с нуля»

pfs calc all && pfs export --six-pager && pfs export

«Найти, откуда число в документе»

pfs claim list --kind fact      # все факты
pfs impact C016                 # кто на это ссылается

«Сверить вики и репозиторий»

grep -rn "Шаг N/12" projects/*/outputs/REPORT.md   # маркер прогонa в отчёте
grep -c "C0" projects/*/claims.jsonl               # объём реестра утверждений

Ещё кейсы из практики

Симптом	Причина	Решение
pfs status показывает чужой проект	активный проект выбран в другом каталоге/сессии	pfs list → pfs use <нужный>; или одноразово: pfs --project <slug> status
pfs decision due пустой, а вы ждали напоминание	у решения нет --review даты или она в будущем	при создании D### указывайте --review YYYY-MM-DD; проверить — pfs decision list
pfs kb search не находит известную карту	индекс устарел после правок knowledge/	pfs kb index (пересборка + проверка связей)
pfs data profile падает на большом CSV	файл больше памяти или нестандартный разделитель	проверьте кодировку/разделитель; уменьшите выборку для профиля; XLSX — укажите --sheet
В Excel-книге не тот лист активен	норма: книга открывается с листа «Ввод»	параметры правьте на «Ввод» — расчётные листы пересчитаются
pfs interview save записал как синтетику, а это реальное интервью	не указан origin	реальное интервью регистрируйте pfs source add <файл> --origin interview
pfs media add отказал в описании	описание пустое или содержит интерпретации	описание = только видимое/слышимое; интерпретации — отдельными C###
pfs ux scaffold требует источник	каркас строится по зарегистрированному источнику	сначала pfs source add материала, затем pfs ux scaffold S### --focus "…"
«собери six-pager» отказался	не готовы документы 02/03/04/06	дождитесь шагов situation…validation или завершите текущий шаг
pfs export --deck сделал HTML, а нужен PPTX	дека — HTML 16:9 по дизайну	PPTX — через officecli / навык deck; HTML открывается в браузере и печатается в PDF
pfs cost --window показывает не то	окно фильтрует по времени транскриптов	уточните диапазон: --since / --until ISO-датами
Хук пишет в лог, но всё работает	предупреждение, не ошибка	читайте hook_errors.log; сессия продолжается по дизайну
macOS: «Permission denied» на .env	права файла	chmod 600 .env; файл не должен быть в git (git check-ignore .env)
Агент предлагает импорт внешних планов	есть skill gsd-import / маршрутизация	решение за вами: импорт проходит проверку конфликтов с вашими решениями

Диагностический чек-лист (2 минуты)

1. pfs doctor — Python 3.9+? PDF-инструменты? число карт (88)? активный проект?
2. pfs status — тот ли проект? на каком шаге? есть ли ожидание человека?
3. pfs next — просроченные обязательства? открытые вопросы?
4. pfs check --strict — какие дефекты документов?
5. .claude/hooks/hook_errors.log — свежие записи?
6. python3 -m unittest discover -s tests — 103 теста зелёные?

Если все шесть пунктов в норме, а проблема осталась — воспроизведите кейс на тестовом проекте (pfs new "Тест" "…") и откройте issue.

Эскалация

Не нашли симптом? Порядок действий:

1. pfs doctor + pfs status + pfs next — в 80% случаев ответ здесь.
2. Журнал: projects/<slug>/log.jsonl и .claude/hooks/hook_errors.log.
3. FAQ — те же кейсы в формате «вопрос-ответ».
4. Issue в https://github.com/Fighter90/product-factory-strategist — приложите вывод pfs doctor, симптом и ожидаемое поведение (без закрытых данных).

Смежные: FAQ · Glossary · Quality-Gates · Security-and-Privacy · Home