Mcp Attribution Worktree

MCP Attribution Worktree

Process MCP and skills-related attribution issues as an auditable maintenance workflow instead of ad-hoc debugging.

What this skill does

Use this skill to:

• fetch pending MCP and skills-related attribution issues from the local report API
• inspect issue detail plus representative runs before making any status decision
• map failures back to concrete mcp/src tools, config/source/skills, or classify them as environment / grader / duplicate noise
• update attribution issues with concise evidence, owner=codex, and links to external GitHub work
• isolate each actionable repair in its own Worktrunk worktree and branch
• carry actionable issues through repo repair and PR creation instead of stopping at issue state updates
• continue from existing GitHub issues or PRs when later review or evaluation feedback shows the first direction was incomplete or wrong
• run a real post-PR evaluation when an evaluation interface is available, and use that result to decide whether another repair loop is needed

Do not use this skill for

• generic bug fixing without attribution evidence
• unrelated attribution categories that do not map to mcp/src or config/source/skills
• bulk repo changes unrelated to a specific attribution issue
• direct database or backend mutation outside the documented report API endpoints

Workflow

1. Start with focused tool and skill backlog queries. 2. Process one issue at a time. Never mix evidence, notes, or worktrees across issues. 3. Run the existing-artifact preflight before choosing the representative run: read issue detail, current notes, existing externalUrl, and the state of any linked GitHub issue or PR. If a GitHub issue or PR already exists, treat it as part of the current state, not a finished endpoint. 4. Read at least one run's result and trace. Prefer to also read evaluation-trace. 5. Check the relevant implementation in mcp/src or config/source/skills before deciding whether the issue is actionable. 6. When the failure is caused by model misunderstanding, prefer repairs that translate repo-specific behavior into concepts the model already knows well. Reuse familiar abstractions, canonical API names, and one safe example instead of adding long product-specific explanations. 7. If the issue is actionable in repo code or skills content, do not stop at attribution triage. Open or link the matching GitHub issue, create a dedicated Worktrunk worktree, implement the fix, validate it, and prepare a PR. 8. If review comments, review decisions, or later evidence show the direction is wrong, start another focused iteration from the existing GitHub issue or PR context and continue improving instead of treating the first PR as final. 9. Update attribution fields through the report API after you have the right evidence, and update them again when the GitHub issue, PR, or evaluation result becomes available. 10. Before changing an attribution to resolved, run a closure preflight on the linked GitHub artifact again: reread the latest PR comments, review comments, review decisions, and issue comments after the most recent code push or evaluation result. 11. When a real evaluation interface exists, run a post-PR evaluation and use the result plus the closure preflight to decide whether to continue iterating or mark the issue closed. 12. Only stop after the issue is either clearly non-actionable or has been carried through the repair loop as far as the current environment allows.

Common requests

• "Automatically process the pending MCP attribution issues."
• "Look at the tool and skills attribution backlog, fix the real issues, and update attribution with evidence."
• "Find valuable MCP attribution problems and fix them in isolated worktrees."
• "For each tool issue, decide whether it is a real mcp/src bug or just evaluation noise."
• "Continue iterating on the existing issue or PR after review comments."
• "After opening the PR, run a real evaluation and fix the next round if it still fails."

Routing

Model-oriented repair heuristic

When attribution evidence shows the model is failing because a tool or skill exposes repo-specific semantics in an unfamiliar way, prefer repairs that reduce translation work for the model.

• Map the behavior to concepts the model already knows well, such as MongoDB updateOne or updateMany, HTTP methods, SQL CRUD verbs, filesystem path conventions, or common SDK idioms.
• Keep model-facing guidance short and high-signal. One canonical safe example is usually better than a long product-specific explanation.
• Explicitly name dangerous defaults or footguns when they are easy for the model to miss, such as replacement vs partial update, destructive writes, ambiguous path resolution, or auth-sensitive side effects.
• Prefer changing the tool description, parameter description, skill wording, or generated docs when that is enough to correct the model's mental model. Do not jump to implementation changes if the real gap is contract clarity.
• Do not assume the model will infer hidden semantics from traces, backend behavior, or evaluator expectations. If a safe rule matters, state it directly where the model sees it.

Operating rules

• Only update attribution issues through the local report API.
• Treat owner as fixed: always set it to codex when you patch an attribution.
• Before any new iteration, always inspect the latest attribution notes, externalUrl, linked GitHub issue or PR status, and any available PR comments or review decisions.
• Before moving any issue to resolved, always perform a fresh closure sweep on the linked issue or PR after the latest push or evaluation has completed. Do not rely on an earlier preflight.
• Do not change resolutionStatus until you have read at least one related run's result and trace.
• Do not mark an issue resolved without clear closure evidence such as an existing GitHub issue, PR, merged fix, or a verified duplicate that already has external tracking.
• Do not mark an issue resolved if there are unread or unaddressed PR comments, review comments, review decisions, or issue comments that arrived after the last time you inspected the linked artifact.
• Keep notes short but auditable. Include the representative run, the main failing signal, and the code or tool signal that supports the conclusion.
• If the evidence is incomplete, keep the issue todo or move it to in_progress and explicitly state what is still missing.
• For a real and repairable issue in mcp/src or config/source/skills, the default expectation is full follow-through: attribution triage, GitHub issue linkage, isolated worktree repair, validation, and PR creation.
• When the likely root cause is model misunderstanding rather than backend behavior, first try to repair the model-facing contract: clearer tool descriptions, safer parameter wording, skill guidance, canonical examples, and explicit warning about dangerous defaults.
• When the fix belongs to CloudBase skill content, edit config/source/skills/ as the source of truth. Do not treat the root skills/ directory as the source for those external skills.
• Only stop at status-only attribution updates when the issue is non-actionable, blocked by missing evidence, blocked by missing Worktrunk, or clearly outside MCP repo control.
• Do not use broad uncategorized backlog queries as the default source of work. Only use them in explicit fallback mode when category labels are incomplete or the user asks for a full backlog sweep.
• Items discovered through fallback broad queries must not enter the repair queue until run evidence clearly shows they belong to mcp/src or config/source/skills.
• Prefer one sub-agent per issue when sub-agent support exists. Give each sub-agent ownership of exactly one issue. If sub-agents are unavailable, process issues serially and keep a strict one-issue-at-a-time context.
• If a repair is needed, use Worktrunk's wt workflow for the isolated worktree. If wt is unavailable, stop and report that Worktrunk is missing instead of silently falling back to a shared checkout.
• Never reuse the same worktree for multiple attribution issues.
• Do not open or update GitHub issues until you have enough run evidence to explain the problem clearly.
• If an issue already has a GitHub issue or PR, read its current state before starting a new branch or changing direction: open or closed status, latest comments, review decisions, and whether the linked work is already stale or superseded.
• Review comments and post-PR evaluation failures are part of the same repair loop. Use them to drive another iteration instead of prematurely closing the attribution.
• If a real evaluation interface is available, prefer leaving the attribution in_progress until the repaired branch or PR passes a fresh evaluation round.
• Do not claim validation success from reasoning alone. Use the evaluation API and the final run result whenever that interface is available.

Required preflight

Before starting a fresh diagnosis or code iteration for an attribution issue, complete this checklist in order:

1. Read the attribution detail plus the latest notes. 2. Read externalUrl if present. 3. If externalUrl points to a GitHub issue, check whether it is open or closed and whether later comments changed the fix direction. 4. If externalUrl points to a PR, check whether it is open, merged, closed, or superseded. 5. Read PR comments, review comments, and review decisions before deciding whether to continue the same branch or start a new iteration. 6. Only after that, pick the representative run and continue into result, trace, and evaluation-trace.

Required closure preflight

Before changing an attribution to resolved, complete this checklist in order even if you already did the normal preflight earlier:

1. Reopen the linked GitHub issue or PR. 2. Re-read the latest top-level comments, review comments, and review decisions. 3. Confirm whether any comment arrived after the latest code push, PR update, or evaluation result. 4. If new feedback exists, keep the attribution in_progress and continue the loop. 5. Only if there is no newer unresolved feedback, evaluate whether closure evidence is now strong enough.

Quick commands

curl -s 'http://127.0.0.1:5174/api/attributions?category=tool&resolutionStatus=todo&limit=50'
curl -s 'http://127.0.0.1:5174/api/attributions?category=skill&resolutionStatus=todo&limit=50'
curl -s "http://127.0.0.1:5174/api/attributions/<issueId>"
curl -s "http://127.0.0.1:5174/api/runs/<caseId>/<runId>/result"
curl -s "http://127.0.0.1:5174/api/runs/<caseId>/<runId>/trace"
curl -s "http://127.0.0.1:5174/api/runs/<caseId>/<runId>/evaluation-trace"
wt switch --create feature/attribution-<slug>
gh issue create --repo TencentCloudBase/CloudBase-MCP
gh pr view <number> --comments --repo TencentCloudBase/CloudBase-MCP
gh pr create --repo TencentCloudBase/CloudBase-MCP
curl -s -X POST http://127.0.0.1:5174/api/evaluations

Minimum self-check

• Did I complete the existing-artifact preflight before starting a new diagnosis or code iteration?
• Did I inspect at least one related run's result and trace before changing status?
• Did I keep this issue isolated from every other issue?
• Is the issue actually actionable in mcp/src, config/source/skills, or is it environment / grader noise?
• If the issue was actionable, did I continue into GitHub issue / worktree / PR work instead of stopping at triage?
• If there was already a PR or review thread, did I continue from that feedback instead of ignoring it?
• If a real evaluation interface was available, did I run a fresh evaluation before treating the issue as closed?
• Did I base the validation conclusion on the final evaluation result instead of my own guess?
• If I patched the attribution, did I keep the change limited to resolutionStatus, owner, notes, and externalUrl when relevant?
• If I started a fix, does it live in its own Worktrunk worktree and branch?
• If the issue was caused by model misunderstanding, did I reduce model-facing complexity by mapping repo-specific behavior to familiar concepts and by explicitly naming dangerous defaults?
• If I marked something resolved, is there explicit closure evidence?
• If I marked something resolved, did I re-read the latest PR comments, review comments, review decisions, and issue comments immediately before closing it?

Evaluation Verification

Purpose

Use this reference when you need to verify that a proposed fix or repair direction actually works in a real evaluation run.

Core rule

Do not treat implementation or static reasoning as proof of success.

When the AI Coding Eval Report API is available, validation means:

1. trigger a real evaluation run 2. wait for it to finish 3. read the final result 4. decide pass or fail from the returned run result

Required flow

After you believe the implementation is ready:

1. POST /api/evaluations 2. record caseId and runId 3. poll GET /api/evaluations/{caseId}/{runId} 4. once finished, read GET /api/runs/{caseId}/{runId}/result 5. optionally read trace and evaluation-trace if the run failed or is ambiguous

Do not claim "validated" before step 4 is complete.

Required request shape

The request body must include:

• caseId
• config

Typical config fields:

• mcp
• tcbCli
• skillsMode
• mcpPackage
• skillsRepo
• skillsRef
• skillsPath
• allInOneSkillsRepo
• allInOneSkillsRef
• allInOneSkillsLocalPath
• apiSkillsRepo
• apiSkillsRef
• apiSkillsPath
• agentType
• model
• evalModel
• maxTurns
• caseTimeoutSeconds
• evaluationTimeoutMs

Local build expectations

When local MCP code is under test:

• build mcp first
• pass the absolute path to mcp/dist/cli.cjs as config.mcpPackage

When skillsMode=allinone is under test:

• build the local all-in-one skill bundle first
• pass the absolute bundle path as config.allInOneSkillsLocalPath

Result interpretation

Use the final run result as the source of truth.

Pass

Treat the evaluation as passed when:

• result.status == "pass"
• and there is no failed test signal

Fail

Treat the evaluation as failed when any of these are true:

• result.status == "fail"
• result.status == "error"
• result.status == "timeout"
• tests.failed > 0
• error is present

Failure follow-up

If the run fails:

1. capture the failure summary 2. inspect trace and evaluation-trace 3. decide whether the problem is:

• still the same root cause
• a new regression
• environment noise

4. continue the repair loop if needed

Reporting format

Every verification summary should include at least:

• caseId
• runId
• evaluation status
• overall score when available
• tests passed / failed / total when available
• whether validation passed
• failure reason when it did not pass

Attribution rule

If real evaluation is available, do not move a repairable issue to resolved until the final evaluation result supports closure or there is another explicit closure reason.

Iteration Loop

Purpose

Use this reference when an attribution issue already has a linked GitHub issue or PR, or when a new review or evaluation result arrives after the first repair attempt.

Core rule

Treat GitHub issues, PRs, review comments, and fresh evaluation results as part of the same repair loop.

Do not assume that:

• the first PR is final
• opening a PR is enough to mark the attribution closed
• an existing externalUrl means no more work is needed

Existing artifact first

When an attribution already has externalUrl or notes pointing to previous work:

1. Read that issue or PR first. 2. Capture its current state first:

• issue open or closed
• PR open, merged, closed, or superseded

3. Read comments, review comments, review decisions, and any follow-up discussion. 4. Compare that feedback with the latest attribution run evidence. 5. Decide whether to continue the same approach or redirect it.

Do not start a new branch, worktree, or diagnosis pass until this check is complete.

Closure sweep

Before you change an attribution from in_progress to resolved, repeat the artifact check one more time even if you already did it at the start of the iteration.

You must re-read:

1. the latest top-level PR comments 2. review comments 3. review decisions 4. linked issue comments when relevant

Treat any newer unresolved feedback as a new iteration signal. Do not close the attribution off an older snapshot of the PR.

Continue vs restart

Continue the same PR

Prefer continuing the same PR when:

• review feedback asks for corrections, tightening, or missing edge cases
• the overall repair direction is still correct
• the next change is an iteration, not a different root-cause theory

Start a new iteration path

Prefer a new worktree or branch when:

• review or fresh evaluation shows the first direction was wrong
• the repair target moved from mcp/src to config/source/skills, or vice versa
• the PR became too mixed or too far from the new diagnosis
• the linked PR is closed, stale, or superseded and continuing it would hide the new root cause

Post-PR evaluation

If a real evaluation interface exists:

1. run a fresh evaluation after the PR or branch update 2. inspect the resulting run and failed checks 3. decide whether:

• the issue is now closed
• the issue needs another iteration
• the issue turned out to be grader or environment noise

Use that new evaluation as stronger closure evidence than static reasoning alone.

Attribution state during iteration

Keep in_progress

Keep the attribution in_progress while:

• a PR exists but review feedback is unresolved
• a fresh evaluation still fails
• the next iteration is already clear

Move to resolved

Move to resolved only when:

• the PR or linked issue provides explicit closure
• and any available fresh evaluation no longer shows the original failure mode
• and the closure sweep found no newer unresolved PR comments, review comments, review decisions, or issue comments

Move to invalid

Move to invalid when later review or evaluation shows:

• the original attribution was wrong
• the real failure was environment or grader noise
• no repo or skill-source change is actually needed

Notes guidance

When iterating, append evidence like this:

iteration=<n>; prior=<issue or PR link>; new_signal=<review or eval summary>; conclusion=<continue or redirect>

This keeps the attribution auditable across multiple rounds.

Mandatory iteration checklist

Before each new iteration:

1. read attribution notes 2. read externalUrl 3. inspect linked issue or PR state 4. read comments and review decisions 5. decide continue vs restart 6. only then inspect the next representative run

Before resolved, repeat steps 2-4 after the latest push or evaluation result so the closure decision is based on a fresh artifact read rather than an older preflight snapshot.

Report API Workflow

Purpose

Use this reference to process MCP attribution issues through the local report API in a repeatable, auditable order, while treating attribution updates as one part of a larger repair loop rather than the final deliverable.

Allowed endpoints

Use only these attribution endpoints for attribution state:

• GET /api/attributions
• GET /api/attributions/:issueId
• GET /api/runs/:caseId/:runId/result
• GET /api/runs/:caseId/:runId/trace
• GET /api/runs/:caseId/:runId/evaluation-trace
• PATCH /api/attributions/:issueId

Do not mutate attribution state through any other backend path.

API reality check

Trust the live API responses over the current OpenAPI schema when they disagree.

At the time of writing, the live attribution responses include fields such as resolutionStatus, owner, notes, and externalUrl, while the published OpenAPI schema may still show the older status-only shape.

Likewise, run-level execution problems such as worker ExecutionError, error_during_execution, or provider 429 usage exceeds frequency limit should be treated as run result error, not normal assertion fail.

Baseline query

Start with:

GET /api/attributions?category=tool&resolutionStatus=todo&limit=50

Then query explicit skills backlog too:

GET /api/attributions?category=skill&resolutionStatus=todo&limit=50

Use the first query to get the focused MCP tool backlog.

Use the second query to get explicitly labeled skills backlog. Do not run a broad uncategorized backlog query by default.

Fallback query

Only if category labeling looks incomplete, or if the user explicitly asks for a full todo sweep, run:

GET /api/attributions?resolutionStatus=todo&limit=100

Use this broader query only to discover candidates that may have been miscategorized.

Do not rely on the broad query as the default work source.

Per-issue sequence

For each candidate issue:

1. Read issue detail with GET /api/attributions/:issueId. 2. Review the current notes and externalUrl. 3. If there is already a linked GitHub issue or PR, read it as existing repair context before touching run evidence. 4. Capture the state of the linked artifact:

• issue open or closed
• PR open, merged, closed, or superseded
• latest comments, review comments, and review decisions

5. Only after that, review the runs array and pick one representative run. 6. Read:

• result
• trace
• preferably evaluation-trace

7. Summarize the concrete failure signal. 8. Only then decide whether the issue is non-actionable or should proceed into repo repair. 9. Patch the issue with the current evidence. 10. If the issue is actionable in mcp/src or config/source/skills, continue into the worktree and PR workflow instead of stopping here. 11. If the issue already has a linked PR, use its current status plus later review or evaluation evidence to decide whether the same line of work should continue or whether a new iteration is needed.

Existing-artifact preflight

Before starting a new iteration, always check:

1. current attribution notes 2. externalUrl 3. linked GitHub issue or PR state 4. latest comments and review decisions on the linked GitHub artifact

Do not skip this preflight just because the attribution already has a linked PR. The purpose is to decide whether the next action is:

• continue the same PR
• update the linked issue first
• start a new worktree and branch because the previous direction is stale or wrong

Closure preflight

Do this again immediately before moving an attribution to resolved, even if you already completed the normal preflight earlier in the same session.

Check:

1. the latest linked GitHub issue or PR state 2. top-level PR comments 3. review comments 4. review decisions 5. issue comments when externalUrl points to an issue 6. whether any of the above arrived after the latest code push, PR update, or fresh evaluation result

If new unresolved feedback exists, do not mark the attribution resolved. Move it back to or keep it at in_progress and continue the repair loop.

Working set rules

Build the default working set from two buckets:

1. issues returned by the focused category=tool query 2. issues returned by the focused category=skill query

Deduplicate by issueId before processing.

Only in fallback mode, add a third candidate bucket:

3. issues returned by the broader todo query that clearly map to:

• config/source/skills
• skill activation
• skill content
• skill routing
• skill knowledge gaps

Fallback-mode candidates do not become real repair work automatically. They must first satisfy stronger evidence checks from result, trace, and evaluation-trace.

Run selection policy

Prefer the run that is most useful for diagnosis:

1. latest failed run 2. lowest score run 3. highest-signal run with the clearest tool or evaluation failure

If there are multiple similar runs, read the most recent one first and only read more runs if the first run is ambiguous.

What to inspect in each run

Result

Check:

• overall status
• overall score
• failed tests or checks
• timeout or environment-level failures
• whether the failure is a true task failure or an execution failure that should be normalized to error

Normalization rule:

• use fail for normal checker or task failures
• use error for worker / provider / execution failures, including rate limiting such as 429 usage exceeds frequency limit
• if you confirm a historical attribution was written with the wrong run status, correct the record before treating the issue as product evidence

Trace

Check:

• actual conversation decisions
• which tools were called
• whether the tool choice matched the task
• tool call failures, retries, malformed arguments, or missing follow-up steps

Evaluation trace

Use this to identify:

• the exact failed check name
• whether the failure is about missing evidence, incorrect value, or missing action
• whether the run failed because of MCP output, grader expectations, or external environment

Patch policy

When patching an attribution:

• always set owner to codex
• keep notes concise and auditable
• only set externalUrl when you have a real GitHub issue or PR link
• do not modify unrelated fields

Treat PATCH as a checkpoint, not the entire job. For a real MCP defect, you will usually patch at least twice:

1. once after diagnosis, usually as in_progress 2. again after GitHub issue or PR linkage, usually with a stronger closure state

If real evaluation is available, you may patch a third time after the fresh evaluation result is known.

Status rules

todo

Keep todo when:

• no one has really investigated the issue yet
• the run evidence is incomplete or contradictory
• you cannot tell whether the issue is actionable in mcp/src

in_progress

Use in_progress when:

• the issue is real and you are actively following it up
• a repo fix or external issue is needed but closure is not complete yet
• you have a strong direction but still need more validation

This is the default state for actionable issues before the PR or final closure link exists.

It is also the default state when a PR exists but review feedback or fresh evaluation still requires another iteration.

resolved

Use resolved only when there is clear closure evidence, for example:

• an existing GitHub issue or PR already tracks the exact problem
• the fix is already implemented and verified
• the issue is clearly a duplicate of an already tracked and linked problem

Never mark resolved from intuition alone.

Do not mark resolved just because you understand the bug. Mark it only after you have explicit closure evidence.

Do not mark resolved from a stale artifact read. If a linked PR or issue exists, you must complete the closure preflight immediately before patching resolved.

If a post-PR evaluation interface is available, prefer using that fresh evaluation result as part of the closure evidence.

invalid

Use invalid when evidence shows:

• the attribution is a false positive
• the failure is purely environment-related
• the grader expectation is wrong while MCP behavior is already correct
• the issue does not require repo action

Notes template

Use a compact evidence record like this:

run=<caseId>/<runId>; result=<status>; score=<score>; failed_check=<check>; tool_signal=<tool or module>; code_signal=<file or none>; conclusion=<short conclusion>

Add one more clause when needed:

next=<missing evidence or next action>

External URL policy

Set externalUrl only when you have an exact link to:

• a matching GitHub issue
• a matching PR

Do not put search results or speculative links into externalUrl.

Red flags

Stop and keep the issue unclosed if any of these are true:

• you have not read at least one result and trace
• the only signal is the attribution title with no run evidence
• the failure is mixed across multiple unrelated problems
• you cannot tell whether the problem lives in MCP code, the environment, or the grader

Also stop short of resolved if you have not yet completed the GitHub issue / worktree / PR loop for an actionable repo bug.

Also stop short of resolved if there are newer PR comments, review comments, review decisions, or issue comments that have not been re-read after the latest push or evaluation.

Sub-agent Orchestration

Purpose

Use this reference when you are dispatching one or more sub-agents to process MCP attribution issues.

The goal is to keep each worker issue-scoped, audit-friendly, and resistant to premature closure.

Core rule

One sub-agent owns exactly one attribution issue.

Do not give one worker multiple issues. Do not mix worktrees, evidence, or PR context across issues.

Dispatcher responsibilities

The parent agent or dispatcher must:

1. fetch the backlog 2. deduplicate issues 3. assign one issue per worker 4. include the exact issueId and title in the worker prompt 5. require the worker to read the skill plus the relevant references first 6. require the worker to report back:

• attribution conclusion
• current attribution status
• worktree and branch
• GitHub issue or PR URL
• latest evaluation case and run when relevant
• touched files
• remaining blockers

The dispatcher must not assume a worker is done just because it returned a PR URL.

Worker contract

Every worker prompt should explicitly require this sequence:

1. read attribution detail 2. read current notes 3. read externalUrl when present 4. read linked GitHub issue or PR state 5. read top-level PR comments, review comments, and review decisions when a PR exists 6. only then read representative run result and trace 7. decide actionable vs invalid 8. if actionable, use wt to create an isolated worktree 9. implement the fix and run the smallest relevant validation 10. create or update the GitHub issue or PR 11. run a real evaluation when available 12. perform a closure sweep before changing anything to resolved 13. patch attribution only through the report API

Required worker prompt clauses

Include clauses like these in every worker prompt:

• "You are responsible for exactly one issue."
• "Do not process any other issue."
• "Do not use the shared checkout for code edits."
• "Use Worktrunk for any repairable issue."
• "Read PR comments, review comments, and review decisions before deciding next steps."
• "Before marking the attribution resolved, re-read the latest PR comments, review comments, review decisions, and issue comments after the latest push or evaluation result."
• "If unresolved newer feedback exists, keep the attribution in_progress."
• "Update attribution only through http://127.0.0.1:5174/api/...."
• "owner must be codex."

Recommended worker output format

Ask workers to return:

issue conclusion:
attribution status:
worktree / branch:
GitHub issue / PR:
evaluation caseId / runId / result:
modified files:
remaining blockers:

This makes it easy for the dispatcher to apply closure-sweep checks consistently.

Closure-sweep rule for dispatchers

Even if a worker says the issue is closed:

1. reopen the linked PR or issue yourself 2. check whether there are newer comments or review signals 3. only then accept a resolved recommendation

If the dispatcher finds newer unresolved feedback, override the worker's closure and move the issue back to in_progress.

Failure modes to guard against

• worker reads run evidence but skips PR comments
• worker closes after a passing evaluation without re-reading the PR
• worker treats a PR URL as sufficient closure
• worker continues an old PR without checking whether review changed the direction
• worker edits code in the shared checkout instead of a worktree
• worker handles multiple issues in one prompt and contaminates context

Minimal dispatcher checklist

• Did each worker get exactly one issueId?
• Did each worker prompt require preflight before run diagnosis?
• Did each worker prompt require closure sweep before resolved?
• Did I independently verify any worker-proposed resolved state against the latest PR or issue feedback?

Value Triage

Purpose

Use this reference to decide whether a tool attribution issue or a skills-related attribution issue is actually valuable, whether it belongs in mcp/src or config/source/skills, how to map the failure to the right code surface, and whether the agent should continue into a repo repair loop.

High-value issue criteria

Treat an issue as high-value when most of these are true:

• it affects a core MCP capability
• it reproduces across more than one run, or has a very low score on a critical path
• the failing signal points to missing capability, bad defaults, incomplete return data, or weak operator guidance
• you can map the failure to one or more specific modules in mcp/src
• fixing it would improve future agent behavior, not just one isolated run

Lower-value or non-actionable cases

Be cautious when the issue looks like one of these:

• browser or runtime dependencies missing in the evaluation environment
• temporary CloudBase platform instability
• grader schema mismatch while the MCP output already contains the correct substance
• duplicate attribution already tracked elsewhere
• a flow that fundamentally requires human interaction in a non-interactive evaluation environment

These often end up as invalid or remain todo until stronger evidence appears.

Decision ladder

For each issue, decide in this order:

1. Is the failing signal real? 2. Is it caused by MCP code or design? 3. If yes, is there a specific module or tool boundary to change? 4. If no, is it an environment issue, grader issue, or duplicate? 5. Is the issue strong enough to justify a GitHub issue, repo fix, and PR? 6. If a PR already exists, does the next iteration belong on that line of work or does the direction need to change?

When the category is not explicitly tool, still include the issue if the title, detail, trace, or evaluation evidence shows that the failure belongs to skill activation, skill content, skill routing, or missing knowledge under config/source/skills.

Common categories

Real MCP defect

Typical signs:

• missing fields that the underlying tool should reasonably return
• parameters are hard to use, misleading, or silently wrong
• tool output shape prevents downstream extraction
• important next-step guidance is absent in a known failure mode

Typical outcome:

• in_progress if work is still ongoing
• resolved if there is already an external issue, PR, or landed fix

Default agent action:

• continue into worktree repair unless blocked

Grader or output-contract mismatch

Typical signs:

• the trace and result contain the required substance
• the checker expects a different field name or nesting pattern
• the MCP behavior is reasonable, but the evaluator wants another schema

Typical outcome:

• often invalid
• sometimes in_progress if you decide to improve MCP output shape anyway

Default agent action:

• do not open a repair worktree unless you intentionally decide to change MCP output compatibility

Environment or platform issue

Typical signs:

• missing browsers or system packages
• transient provisioning failures outside MCP control
• human-login flows used in headless automation

Typical outcome:

• usually invalid
• or todo if you still need stronger evidence

Default agent action:

• explain why this should not turn into a repo fix

mcp/src mapping table

Use this map to move from attribution title to code inspection quickly.

Code review checklist for attribution triage

Before concluding a tool issue is actionable, verify:

• the tool is actually registered
• the relevant schema or handler exposes the needed capability
• the returned content matches what the agent would realistically need
• the trace failure is not caused by wrong tool choice by the model
• the problem is not already fixed on the current branch
• for skills-related issues, the true source of truth is under config/source/skills/, not the root skills/ maintenance directory

Conclusion patterns

Use one of these conclusion shapes in notes:

• real_mcp_gap: the tool or output is genuinely incomplete
• guidance_gap: the tool exists, but the usage contract is too weak
• grader_mismatch: MCP output is adequate, evaluator expects another shape
• environment_noise: the run failed outside MCP control
• duplicate_external: already tracked elsewhere

Escalation rule

Open or link a GitHub issue only when the problem is both:

• real enough to justify maintenance work
• specific enough that another maintainer could act on your notes without redoing the entire investigation

When those two conditions are met and the problem lives in mcp/src, do not stop at issue linkage. Continue into isolated repair and PR creation unless the environment is explicitly blocked.

Apply the same rule when the problem lives in config/source/skills/: continue into isolated repair and PR creation unless blocked.

Worktree Repair

Purpose

Use this reference when an attribution issue is real, actionable, and worth taking into a repo fix. This is the default next step for repairable MCP issues or repairable CloudBase skill-source issues, not an optional extra.

Worktrunk requirement

This skill is designed around Worktrunk.

Prefer:

• wt switch
• wt list
• wt remove

Do not silently fall back to a shared checkout once you decide to repair an issue. If wt is unavailable, stop and report that Worktrunk is missing.

This keeps issue repair isolated and prevents cross-issue contamination.

One issue, one worktree

Each actionable attribution issue gets:

• one dedicated branch
• one dedicated worktree
• one dedicated GitHub issue or PR trail when needed

Never repair two attribution issues in the same worktree.

Suggested naming

Use a branch name that stays close to the issue:

feature/attribution-<issue-slug>

Examples:

• feature/attribution-envquery-hosting-fields
• feature/attribution-nosql-output-shape

Basic workflow

1. Confirm the issue is actionable from run evidence. 2. Check whether a matching GitHub issue or PR already exists. 3. If a GitHub issue or PR already exists, read its state first:

• issue open or closed
• PR open, merged, closed, or superseded

4. If a PR already exists, read its comments and review state before deciding whether to continue on that line or open a new iteration. 5. If needed, create a GitHub issue with a concise title and evidence summary. 6. Create a dedicated Worktrunk worktree. 7. Implement the fix inside that worktree only. 8. Run the smallest relevant validation for the touched code. 9. Commit and open or update a PR when the fix is ready. 10. If a real evaluation interface exists, run a fresh evaluation after the code change or PR update. 11. Patch the attribution with owner=codex, updated notes, resolutionStatus, and externalUrl when relevant.

Do not stop after step 4 for a repairable issue unless the environment prevents code work, PR creation, or real evaluation.

Worktrunk commands

Create a worktree:

wt switch --create feature/attribution-<issue-slug>

Inspect active worktrees:

wt list

Clean up after merge:

wt remove

GitHub issue workflow

Before creating a new GitHub issue:

• search for the same tool, module, or symptom
• prefer linking an existing issue instead of opening a duplicate

When creating a new issue, include:

• the attribution title
• the representative run
• the failing check or score signal
• the relevant MCP module
• the likely fix direction

Then copy the final GitHub issue URL into externalUrl.

PR workflow

If you implement a fix:

• keep the change scoped to the single attribution issue
• mention the attribution issue ID and representative run in the PR body or commit context
• add the PR URL to externalUrl if that URL is the most direct closure link
• prefer opening the PR in the same session once validation passes

If the PR already exists:

• read its state, comments, and review state before changing direction
• prefer continuing the existing PR when the fix direction is still fundamentally correct
• start a new iteration only when review or new evidence shows the approach itself was wrong

Before changing the attribution to resolved, read the PR state, top-level comments, review comments, and review decisions again after the latest push or evaluation result. Do not close from a stale read.

Do not mark the attribution resolved until the closure link is real and the repair path is clear.

If real evaluation is available, do not treat PR creation alone as closure. Use the fresh evaluation result to decide whether another repair loop is needed.

Status guidance during repair

Before code work starts

Use in_progress if:

• the issue is confirmed
• you know which code path to change
• the worktree or GitHub issue is being prepared

During code work

Keep in_progress while:

• the fix is being implemented
• validation is incomplete
• the PR is not open yet

After closure

Use resolved when:

• there is an exact GitHub issue or PR link in externalUrl
• or the fix is already landed and the closure is explicit in notes
• and there is no newer unresolved PR comment, review comment, or review decision waiting on follow-up

Evidence template for GitHub issue creation

Use a short structure like this:

## Signal

- Attribution: <issueId>
- Run: <caseId>/<runId>
- Score / failure: <summary>

## Why this is actionable

- Relevant module:
- Current behavior:
- Expected behavior:

## Proposed direction

- <short fix direction>

Final check

Before closing the attribution loop, verify:

• the worktree contains only this issue's changes
• the branch name is issue-specific
• externalUrl points to a real GitHub issue or PR
• notes explain why the current status is justified
• the agent did not stop at attribution state changes when repo repair was possible
• if a PR or issue already existed, the agent incorporated that context into the new iteration
• if the attribution was marked resolved, the agent re-read the latest PR comments and review state immediately before closing it