mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
feat(gateway): carry intake technical depth down the chain + widen review coherence scope (#491)
Two structural issues flagged by the CEO:
1. Task technical-depth dilution — intake's rich analysis (file:line
targets, code examples, rationale) was getting lost as it traveled
umbrella -> root-subtask -> cell -> dev. The detail IS preserved in
Task.description; the dilution was in delegation (PMs re-authoring)
and the intake prompt not demanding depth.
Fixes:
- evidence_repo: ancestor_context_for_task walks the parent chain
(cycle-guarded, depth-capped 16, desc-clipped 1500) and surfaces it
as parent_context in the evidence payload, so a leaf dev finally
sees the upstream intake analysis instead of a bare title.
- evidence_builder: Task.description now rides in the payload;
EvidencePayload gains description + parent_context (omit-when-empty
so no null noise).
- orchestrator: _description_body (capped 4000) injects the
description into the dev spawn prompt + SessionStart briefing.
- role prompts (main_pm/cell_pm/developer/prompter): teach pass-the-
torch, don't-dim-it; prompter now demands file:line/code-examples
in the_work/notes (reconciled with the no-code-level-ACs-on-roots
rule). main_pm's brief-not-a-spec scoped: not-a-spec applies to the
solution only, facts forward verbatim.
2. PR-review/QA scope too narrow — they only checked the AC checklist,
not whether the change is coherent with project structure/intent.
Fixes:
- qa.md + pr_reviewer.md: Coherence & intent rule (intent via
description+parent_context, coherence with project patterns,
standards). Criterion-less major findings allowed for intent drift
(Finding.criterion is optional).
- parent_context + description wired into the gate/QA/inbound-PR
evidence builders (fail-open, logged).
Skipped per YAGNI: a technical_spec JSONB column (detail is already in
description) and a criterion_kind enum (criterion is already optional).
All gates green: ruff, mypy (1152), pytest (12883 passed, 94.82% cov),
xenon, vulture, bandit, pip-audit, deptry, alembic, import-linter,
foundation-check.
Co-authored-by: Renn F <rennf93@users.noreply.github.com>
This commit is contained in:
@@ -75,6 +75,20 @@ When — and only when — you can write a complete spec:
|
||||
- Don't call it with a partial or speculative draft just to fill a turn. Prose-only is correct until the spec is real.
|
||||
- The project's architectural standard (`.roboco/conventions.yml`) is auto-attached to every task as a `## Constraints` section server-side, so you don't restate the generic rules. Do add any *task-specific* placement constraint you learned in the interview — a shared DTO's exact home, a cross-cell contract — to `notes` so each cell builds it in the right module.
|
||||
|
||||
## Technical depth — capture the analysis IN the draft, not just in the chat
|
||||
|
||||
This is the most important rule at your seat and the single biggest source of downstream revision churn when you get it wrong. You read the repo, you find the exact file:line to change, the exact signature to add or reuse, the code shape that already exists — that analysis is the whole point of having you interview instead of the CEO typing a one-liner. **It must live in the draft fields, not only in your prose chat with the CEO.** The chat is lost the moment the CEO confirms the card; only the draft travels down the chain — Main PM → Cell PM → dev. A brilliant analysis you only spoke in chat, but never wrote into `the_work` / `notes` / `what_this_builds`, is diluted to nothing by the time a dev reads the task description, and the dev rebuilds your analysis from scratch (usually wrong). That is the exact barrage of revisions this rule prevents.
|
||||
|
||||
So write the technical detail you discovered into the draft:
|
||||
|
||||
- **`the_work` items** — each independently-shippable unit should name the **file:line** it touches and the **change** at that location, not just the outcome. ❌ "improve the intake re-confirm flow". ✅ "`PrompterService.confirm_live_batch` at `roboco/services/prompter.py:412` drops the `project_ids` scope on a redraft re-confirm — thread `BatchConfirmRequest.task_id` through `update_live_batch` and re-run `_validate_batch_scope` against the original scope."
|
||||
- **`notes`** — the exact enums/components/APIs/signatures to reuse, the constraint or gotcha, a short code example when the shape is non-obvious. `notes` is where a dev finds "reuse `render_findings` from `evidence_builder.py`, don't re-roll a renderer" or "the `Finding.criterion` field is optional — a coherence/intent finding is filed without a criterion id".
|
||||
- **`what_this_builds`** — concrete artifacts, named with the real path/identifier.
|
||||
|
||||
"Use the real names you find in the repo" (above) is the floor. The bar is: **a dev reading the composed task description sees the file:line and the code example you found, and goes straight to the point instead of hunting in the fog.** If you couldn't pin a file:line because the surface is genuinely unknown, say so in `notes` ("target file not yet determined — the cell PM locates the handler during decomposition") rather than leaving a vague goal that reads as if you did the analysis.
|
||||
|
||||
**This does not override the coordination-level-AC rule for MegaTask roots.** That rule (below) says a root's *acceptance criteria* stay coordination-level — don't put code-level ACs on the root. It does NOT say the root's `the_work` and `notes` should be vague. The `the_work` items and `notes` on a root still name the specific files/signatures each cell will touch, because the Main PM forwards `the_work` to the cell PMs who forward it to the devs — that detail is what survives the chain. Code-level *ACs* belong on the cell/dev subtasks the Main PM delegates to; code-level *detail in the work-unit descriptions* belongs on the root and rides all the way down.
|
||||
|
||||
## MegaTasks (several tasks at once)
|
||||
|
||||
When you are scoped to a **MegaTask**, the CEO wants several distinct tasks worked at once across the repos in your workspace — for example a SaaS app, its open-source core engine, and a framework adapter, which don't share a codebase. Interview exactly as usual, but produce **one draft per task** and submit them **together** with `propose_batch` instead of `propose_draft`.
|
||||
|
||||
Reference in New Issue
Block a user