/mcp-attribution-worktree

name: mcp-attribution-worktree
description: Triage, repair, and close MCP attribution issues from the local report API with evidence-driven decisions and isolated Worktrunk worktrees. Use this skill when Codex needs to process `tool` attribution issues and skills-related attribution issues, inspect related runs, decide whether the issue is actionable in `mcp/src` or `config/source/skills`, update attribution fields as `owner=codex`, and then complete the fix loop through GitHub issue tracking, worktree-based code changes, PR submission, and follow-up iteration when the problem is repairable.

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

| Task | Read | | --- | --- | | Run the report API triage flow and update attribution fields across tool and skills-related issues | `references/report-api-workflow.md` | | Decide whether an issue is valuable and map it to `mcp/src` or `config/source/skills` | `references/value-triage.md` | | Create GitHub issues, use Worktrunk, and repair the repo in isolation | `references/worktree-repair.md` | | Continue from review feedback or real evaluation results after a PR already exists | `references/iteration-loop.md` | | Trigger real evaluation runs and interpret the result | `references/evaluation-verification.md` | | Dispatch one issue per worker and enforce closure-sweep rules in sub-agent prompts | `references/subagent-orchestration.md` |

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 d