Intelligence Loop
The Intelligence Loop
Every objective that runs generates data — rejection notes, context file reads, quality scores, clarity flags. The Intelligence Loop feeds that data back into the next objective run, automatically. No configuration required: the signals are collected as part of normal workflow, and the feedback is injected at the points where it changes behavior.
The loops compound. Rejection categories seed the mission brief agents receive at claim time. Context file reads seed effectiveness scores. Effectiveness scores determine which files get ranked first in future recommendations. After 20–30 completed objectives in a project, agents arrive pre-briefed on the patterns that matter for that type of work. The system gets more useful as it accumulates history — not because anything is configured, but because the flywheel is turning.
Rejection Taxonomy
Seeds everything downstreamEvery time you reject an objective, you select one of six categories alongside your written note. That single click converts free text into structured signal — and that signal feeds the mission brief, the Insights breakdown, and the doc gap detector automatically.
Rejection categories
| Missing acceptance criteria | The spec didn't define a testable condition the agent could verify before requesting review. |
| Wrong scope | The agent executed beyond or below the objective boundary. |
| Tests failing or missing | Code landed without passing or writing the required tests. |
| Code quality | Style, design principle, or convention violation. |
| Partial implementation | The objective was not fully addressed in the run. |
| Architecture drift | The approach conflicts with documented architectural decisions. |
Where it surfaces
- —Rejection drawer — six-option radio group, one click per rejection
- —Insights page — By Rejection Category breakdown with trailing-30 trend
- —Mission brief — top categories for the strategic area, injected at claim time
When to act
"Missing acceptance criteria" is your top category
Your objective template has a structural gap. Make acceptance criteria mandatory in your workflow — objectives without them should not reach the Scheduled lane. The quality score (Loop 2) will surface a warning automatically once this is established.
"Tests failing or missing" appears repeatedly
Agents are not finding or following your testing conventions. Add a testing-conventions context file explicitly naming what gets tested, how test data is managed, and what helpers exist. Then check whether the objective description pattern reminds agents to write tests.
"Architecture drift" shows up more than once in a period
Agents are working from an outdated or missing architecture reference. Review your architecture-decisions context file. If it predates the decisions that are being violated, rewrite the relevant sections. Drift at this rate means the doc is not doing its job.
"Wrong scope" is consistently high
Objectives in this area are being scheduled too broad. Cross-reference with objectives that have quality score warnings for bulk — an acceptance criteria count over 12 bullets is a reliable split signal. Reduce scope before re-scheduling.
"Code quality" is the top category for a specific agent kind
That agent kind is not picking up your conventions. Add an explicit style and convention context file, or extend CLAUDE.md with the patterns being violated. Check whether the agent has access to your linting rules at execution time.
Objective Quality at Source
Shifts quality leftA 0–100 quality score is computed every time an objective is created or updated — no LLM call, no delay, no manual review. It checks structural attributes: acceptance criteria presence, description word count, title specificity, acceptance criteria breadth, and the presence of business value and complexity risk fields. The score and any warnings are returned immediately in the MCP response and shown on the objective card.
Scoring rules
Where it surfaces
- —Objective card — quality indicator for scores below 50
- —Scheduling flow — advisory warning if score is below 40
- —MCP response — qualityScore and qualityWarnings[] returned on every create/update
When to act
Score below 40
Do not schedule. An objective scoring below 40 is missing foundational spec. The most common fix is adding acceptance criteria — this alone is worth 20 points. A well-defined acceptance criteria list forces the scoping work that prevents rejection cycles.
"Title is a vague verb phrase" warning
Rewrite the title as a specific outcome: not "Improve the onboarding flow" but "Reduce onboarding drop-off at the email verification step by surfacing errors inline." The objective title is the agent's primary directive. Vague titles produce scope assumptions that compound into rejections.
"Acceptance criteria count exceeds 12" warning
The objective is too broad for a single agent run. Split it. An objective with more than 12 acceptance criteria will be partially implemented almost every time — agents lose track of completeness at that scope. The right split point is usually the natural boundary between user-facing and implementation concerns.
Planning agent reports qualityWarnings[] in MCP response
Let the agent iterate on the spec before submitting. The MCP response returns specific warnings — the planning agent can refine the description, add acceptance criteria, or flag for human review before the objective is scheduled. This is the most efficient place to fix quality: before any execution has started.
Most objectives in a project score below 60
A systemic writing pattern is the issue, not individual objectives. Establish a team template: title (outcome, not action) → description (context and constraints, 50+ words) → acceptance criteria (3–8 specific, verifiable bullets) → business value (one sentence). Run the backfill worker to score existing objectives and identify which fields are most commonly missing.
Mission Brief & Portfolio Intelligence
Agents arrive pre-briefedEvery time an agent claims an objective, the claim response includes a missionBrief block assembled from signals already computed by the other loops — no additional tool calls, no latency beyond a fast SQL read. The brief tells the agent: what the strategic area's historical pass rate is, which rejection categories are most common for this type of work, which context files have the highest effectiveness for this bucket, and how many pending doc suggestions exist. The Insights page surfaces the portfolio view of the same data for human directors.
missionBrief fields in the claim response
| strategicBucketFirstPassRate | First-pass rate for this strategic area over the trailing 30 completed objectives in the project. |
| topRejectionCategories | The most frequent rejection categories for objectives in this strategic area, drawn from Loop 1 classifications. |
| recommendedContextFiles | Context files ranked by effectiveness for this strategic bucket — highest first-pass association first. |
| specQuality | The current objective's quality score and warnings, so the agent can flag concerns before posting a plan. |
| pendingDocSuggestions | Count of pending documentation improvement suggestions for this project, as a prompt to check context file coverage. |
Where it surfaces
- —MCP claim response — missionBrief block, always present once history exists
- —Insights page — By Strategic Area panel showing first-pass rates per bucket
- —Scheduling flow — advisory warning if the objective's bucket has first-pass below 50%
When to act
Strategic area shows first-pass rate below 50% in Insights
The context files covering that area are inadequate — agents in this bucket are flying without documentation. Identify which context files are supposed to cover this area, read them against recent rejection notes, and rewrite or extend them. Don't schedule more objectives in this bucket until the pass rate recovers. The mission brief will surface the low rate to every agent that claims work here, but that alone doesn't fix the underlying gap.
The mission brief shows no pass rate for this strategic area
Not enough history yet — fewer than 5 completed objectives in this bucket. This is normal early in a project. The signal becomes meaningful after 10–15 completed objectives. Focus on Loop 1 (tagging rejections) to build the dataset faster.
Mission brief consistently shows the same top rejection categories across agents
The issue is not the agent — it's the docs or the objectives for that area. Shared rejection patterns across different agents point to a context or spec problem. Systematic rejection categories are the clearest signal to act on: if “Architecture drift” appears in the brief for every TRUST objective, your compliance context file needs a rewrite.
Scheduling advisory warning fires for a bucket
You have a choice: improve context files before scheduling (the right call for most teams), or schedule anyway and accept a higher rejection rate. If you schedule despite the warning, ensure the objective's acceptance criteria are unusually specific to compensate for thin context coverage.
TRUST or SCALE bucket consistently underperforms BUILD
This is the most common pattern in early-stage agentic teams. BUILD work has obvious docs (architecture, data model, API conventions); TRUST and SCALE work often lacks written context (compliance requirements, SLA definitions, capacity constraints). The fix is always more context files, not better agents.
Documentation Intelligence
Closes the writing loopContext files are only useful if they're accurate and agents are reading them. This loop tracks both. When an agent reads a context file during an active run, that read is recorded. After the run completes — accepted or rejected — the file is credited or debited: first-pass runs increase its effectiveness score; rejected runs decrease it. A weekly worker scans rejection notes, extracts key terms, checks whether any context file covers them, and generates doc gap suggestions when it finds misses. No LLM call required — heuristic term extraction against indexed context file content.
Where it surfaces
- —Context Files page — effectiveness badge on each file (first-pass rate when read, sample count)
- —Context Files page — Suggested Improvements panel with pending doc gap suggestions
- —Mission brief — recommendedContextFiles ranked by effectiveness for the strategic bucket
When to act
Context file shows "below project average" badge
The file is either stale, misleading, or covering the wrong scope for how it's being used. Read the rejection notes from runs where it was read. If the file describes a pattern agents are then violating, the content contradicts current practice and needs to be updated. If the file is about something different from what's being rejected, agents may be reading the wrong file — check the file name for clarity.
Context file shows a very low sample count
Agents are not reading this file. Either the file name doesn't signal what it covers, or agents are finding what they need elsewhere. Rename it to be more descriptive, or review whether the content is duplicated in another file. Files that are never read can't help.
Doc gap suggestion appears in the Suggested Improvements panel
Review the rejection note that triggered it — the suggestion will cite the specific note and objective. If the coverage gap is real, update the relevant context file and push the new content. If the suggestion is already covered elsewhere, dismiss it and check whether the covering file is being read (it may have a naming issue). Nothing auto-writes to your docs — applying requires explicit action from a human or agent.
Pending suggestion count is high (5+)
Your context library is falling behind your codebase evolution. Set aside dedicated time — or a dedicated objective — to apply pending suggestions in bulk. This is the signal that documentation debt is actively costing you in rejection cycles. Each pending suggestion represents a rejection note pattern that isn't covered by any existing file.
No suggestions ever appear
Either your context files are excellent and coverage is high, or agents aren't reading them (and therefore no reads are being tracked). Check whether context file reads are appearing in agent run records. If reads are not being tracked, confirm agents are calling planwright_get_context_file during their sessions — reads only register when fetched via MCP during an active run.
How the loops depend on each other
The loops are independent at the data layer but compound at the insight layer. You can benefit from any single loop without running the others — but the most useful signal (the mission brief) draws from all four.
Dependency chain
What's automatic vs. what requires action
Nothing in the Intelligence Loop blocks workflow. Every computation runs automatically; every action is advisory. The one exception — the rejection category radio click — is the most valuable human input in the entire system. It takes one second and seeds everything else.
| Signal | Automatic | Requires action |
|---|---|---|
| Quality score computed | Every create/update | Fixing the spec is optional |
| Rejection classification | Backfill via worker | One radio click per rejection |
| Strategic bucket pass rate | Updates as work completes | Improving context files is optional |
| Mission brief at claim | Injected into every claim response | None — agents receive it automatically |
| Context file effectiveness score | Worker runs after each completed run | Updating or retiring files is optional |
| Doc gap suggestions generated | Worker runs weekly against rejection notes | Applying or dismissing each suggestion |
Where to look first in a new project
Start tagging rejections immediately — even a handful of classifications unlocks the mission brief and Insights breakdown.
Check the quality score on every objective before scheduling. Anything below 40 is not ready to run.
After 10 completed objectives, open the Insights page and check By Strategic Area. Low-performing buckets tell you which context files are missing.
Review the Suggested Improvements panel on Context Files weekly. Pending suggestions are direct translations of rejection notes into documentation gaps.