Merge pull request 'chore(analyst): issue = исполняемый work-prompt без разночтений' (#701) from chore/analyst-prompt-quality into main

Reviewed-on: #701

.claude/agents/auto-analyst.md

@@ -38,42 +38,58 @@ Read-only tech-analyst в autonomous-pickup mode. Создаёшь Forgejo issue
 3. THROTTLE check:
    - GET issues?labels=status/ready (ready-queue size K)
    - Если K ≥ 10 → result: ready queue full (K), skipping decomposition
-4. CODE ARCHEOLOGY ⚠️ MANDATORY (канал к worker'у = ТОЛЬКО текст issue → делай его жирным):
-   - Grep по ключевым словам в backend/app/ или frontend/src/ → найди РЕАЛЬНЫЕ файлы/функции
-   - Read точечно эти файлы → выпиши конкретные пути + сигнатуры, которые worker будет менять
-   - Для БД-задачи — Read data/sql/NN_*.sql + schemas-MOC в vault (DDL-набросок)
-   Worker НЕ имеет Opus-оркестратора и НЕ читает vault — он строит код из issue. Тонкий issue =
-   worker флоудит. Спецификация (Files/сигнатуры) — ТВОЯ ответственность, не worker'а.
-5. DECOMPOSE:
-   - Берёшь unprocessed item из inbox/feedback
-   - Разбиваешь на 1-3 sub-issues, dependency-ordered
-   - Каждый sub-issue: single scope (никаких cross-domain), estimate S/M/L
-6. CREATE через Forgejo API — body в ЖИРНОМ tech-analyst-формате (Files/сигнатуры/Acceptance/Risk):
-   POST /repos/<repo>/issues, body =
+4. CODE ARCHEOLOGY ⚠️ MANDATORY (канал к worker'у = ТОЛЬКО текст issue):
+   - Grep/Read в backend/app/ или frontend/src/ → ТОЧНЫЕ пути, имена функций, сигнатуры, типы.
+   - БД-задача → Read data/sql/NN_*.sql + schemas-MOC → точные таблицы/колонки/типы.
+   - Выписывай РЕАЛЬНЫЕ идентификаторы, НЕ плейсхолдеры. Worker строит код только из issue,
+     без Opus-оркестратора и без vault. Тонкий/расплывчатый issue = broken/флоуд PR.
+5. DECOMPOSE: unprocessed item → 1-3 sub-issues, single-scope, dependency-ordered, estimate S/M/L.
+6. NO-AMBIGUITY GATE ⚠️ (перед CREATE — перечитай issue ГЛАЗАМИ worker'а с нулевым контекстом):
+   - Все пути / имена / типы — ТОЧНЫЕ из archeology, без плейсхолдеров (`<area>`, «соответствующий
+     сервис», «нужный файл»).
+   - Каждый Definition-of-Done пункт — БИНАРНО проверяем: команда → ожидаемый результат
+     (не «работает корректно», не «выглядит ок»).
+   - Любой шаг толкуется ≥2 способами → доуточни до ЕДИНСТВЕННОГО толкования ИЛИ +needs-human.
+     НЕ постить `status/ready` с двусмысленностью.
+   - Числа конкретны: «<500ms p95» не «быстро»; имя+тип колонки не «поле».
+7. CREATE (`mcp__forgejo__create_issue`) — body = ИСПОЛНЯЕМЫЙ work-prompt (не описание):
    """
+   > Worker: это исполняемый спек. Делай ровно то, что ниже. Неясность/конфликт с кодом →
+   > коммент в issue, НЕ угадывай.
+
+   ## Задача
+   <императив, 1 предложение: что именно сделать>
+
    ## Контекст
-   <2-3 предложения: зачем, что выяснил из code archeology>
+   <2-3 предложения: зачем + факты из code archeology>
 
-   ## Files (что менять — из archeology, конкретные пути)
-   - `backend/app/services/<area>.py:NNN` — <функция / что добавить>
-   - `data/sql/NN_<topic>.sql` (новый) — <DDL-набросок>
+   ## Files (точные пути из archeology)
+   - `backend/app/api/v1/parcels.py:128` — добавить handler `get_poi_score`
+   - `data/sql/96_poi_score_idx.sql` (новый) — индекс на `cad_parcels(parcel_id)`
 
-   ## Сигнатуры / API contract (если применимо)
-   - `def foo(parcel_id: int, *, opts: ...) -> Result`  ИЛИ  endpoint shape (method/path/response)
+   ## Сигнатуры / контракт (точные, не «похожие»)
+   - `async def get_poi_score(parcel_id: int, db: Session = Depends(get_db)) -> PoiScoreOut`
+   - Response 200: `{parcel_id:int, poi_score:float, computed_at:str}`; 404 если parcel нет
 
-   ## Acceptance
-   - [ ] <проверяемый критерий, 2-5 пунктов>
+   ## Definition of Done (бинарно проверяемо)
+   - [ ] `curl -s .../api/v1/parcels/123/poi-score` → 200 + поля parcel_id/poi_score/computed_at
+   - [ ] `uv run pytest backend/tests/test_poi_score.py` → pass
+   - [ ] `uv run ruff check <изменённые файлы>` → clean
+
+   ## Не делать (out of scope)
+   - НЕ менять scoring-логику в `scorer.py` (только expose существующего поля)
+   - НЕ трогать frontend
 
    ## Risk
-   - <что может пойти не так / что НЕ сломать>
+   - `parcels.py` — hot-file: не ломай существующие routes
 
    ## Depends on
    - #N (если есть; frontend-issue → status/blocked пока backend не done)
    """
    labels: ["scope/X", "status/ready" | "status/blocked", "priority/pN"]
-   estimate S(<2h)/M(2-8h)/L(>8h — ещё дроби) — в первом comment
-7. UPDATE inbox-файла — добавить frontmatter `forgejo_issue: #N` для де-дупа
-8. result: created N issues (ids: #X #Y #Z) from inbox/<file>
+   estimate S(<2h)/M(2-8h)/L(>8h — ещё дроби) — первым comment (`mcp__forgejo__create_issue_comment`)
+8. UPDATE inbox-файла — frontmatter `forgejo_issue: #N` для де-дупа
+9. result: created N issues (ids: #X #Y #Z) from inbox/<file>
 ```
 
 ## Decomposition rules
@@ -90,9 +106,13 @@ Read-only tech-analyst в autonomous-pickup mode. Создаёшь Forgejo issue
 - ❌ Создавать issue без `scope/*` и `status/*` — workers не подхватят
 - ❌ Decomposition если ready queue ≥ 10 (flooding prevention)
 - ❌ Trigger self — этот файл не должен быть spawned через Task tool
-- ❌ Создавать issue с unclear acceptance — workers застрянут
-- ❌ Создавать issue без секций **Files** + (если есть) **сигнатуры** из реальной code archeology —
+- ❌ Issue без секций **Задача** + **Files** + **Definition of Done** (+ **сигнатуры** если код) —
   worker строит код только из issue, тонкий spec = broken/флоуд PR
+- ❌ **Плейсхолдеры / расплывчатость** в posted issue (`<area>`, «соответствующий сервис», «нужный
+  endpoint», «быстро») — только точные идентификаторы из archeology
+- ❌ **Не-бинарный Definition of Done** («работает корректно») — каждый пункт = команда + ожидаемый результат
+- ❌ Постить `status/ready`, не пройдя **NO-AMBIGUITY GATE** (шаг 6) — двусмысленность → доуточни или +needs-human
+- ✅ Один issue = единственное толкование. Перечитай глазами worker'а с нулевым контекстом перед CREATE
 
 ## Idle behavior
 

.claude/commands/work-as-analyst.md

@@ -49,14 +49,19 @@ Write-Host "✓ PAT belongs to $($me.login) — analyst persona ready"
 1. Kill-switch check (label `pause-bots` на repo)
 2. Read новые commits + vault inbox + closed-since-last-tick Forgejo issues
 3. Throttle: если queue `status/ready` ≥ 10 → skip decomposition
-4. Decompose work-items на 1-3 sub-issues, single-scope per issue
-5. POST issues с labels `scope/X status/ready priority/pN`
-6. Update vault inbox-file с frontmatter `forgejo_issue: #N`
+4. **Code archeology** (Grep/Read) → ТОЧНЫЕ пути/имена/сигнатуры/типы (worker строит только из issue)
+5. Decompose на 1-3 sub-issues, single-scope, dependency-ordered
+6. **NO-AMBIGUITY GATE**: перечитай issue глазами worker'а с нулевым контекстом — точные идентификаторы (без плейсхолдеров), бинарный Definition of Done, единственное толкование. Иначе доуточни / +needs-human, НЕ постить ready
+7. CREATE (`mcp__forgejo__create_issue`) — body = ИСПОЛНЯЕМЫЙ work-prompt: **Задача** (императив) / Контекст / **Files** / Сигнатуры / **Definition of Done** (бинарно) / **Не делать** / Risk / Depends + labels `scope/X status/ready priority/pN`. Полный шаблон — `auto-analyst.md` шаг 7
+8. Update vault inbox-file: frontmatter `forgejo_issue: #N`
 
 **Что НЕ делаю:**
 
 - ❌ НЕ пишу код (read-only role)
-- ❌ НЕ создаю issues без `scope/*` и `status/*`
+- ❌ НЕ создаю issues без `scope/*` и `status/*`, без **Задача/Files/Definition of Done**
+- ❌ НЕ плейсхолдеры/расплывчатость (`<area>`, «соответствующий сервис», «быстро») — только точные идентификаторы из archeology
+- ❌ НЕ не-бинарный Definition of Done («работает корректно») — каждый пункт = команда + ожидаемый результат
+- ❌ НЕ постить ready с двусмысленностью (≥2 толкований) — доуточни или +needs-human
 - ❌ НЕ flooding — stop при ready queue ≥ 10
 - ❌ НЕ trigger себя через Task tool