execution-trace
Skill2 starsChanged 6 months agoMITView on GitHub
When the user wants to connect requirements to execution evidence such as tickets, PRs, commits, releases, checks, demos, or verification notes. Reads `.agents/project-context.md` and `.agents/requirements.md` first when available, preserves requirement IDs, avoids claiming completion without evidence, and writes a structured `.agents/execution-trace.md` delivery trace.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- decision-captureSkill
- project-contextSkill
- requirements-from-decisionsSkill
- workspace-initSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
41 rules. About 0 are common, 30 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈30
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Use this skill to track:
- Distinctive: line 32
Do not assume trace files belong inside a production code repo.
- Distinctive: line 46
Read it before tracing execution.
- Distinctive: line 48
Follow the project’s stated tracker and repo conventions.
- Distinctive: line 49
Do not invent tracker URLs, repo names, PRs, or review rules.
- Distinctive: line 50
If the requested skill path is missing but a vendor copy is used, record that as an installation/source gap rather than silently proceeding.
- Distinctive: line 52
If it does not exist:
- Distinctive: line 55
Do not invent workflow rules.
- Distinctive: line 68
Read it after project context.
- Distinctive: line 69
Use functional requirements as the primary trace set.
- Distinctive: line 70
Treat non-goals and constraints as scope guards.
- Distinctive: line 71
Treat open requirement questions as blockers or gaps, not shipped work.
- Distinctive: line 77
Ask whether requirements should be drafted first if the user only provided decisions, transcript notes, or vague feature descriptions.
- Distinctive: line 78
Do not create tickets or PR trace rows without requirement-level source context unless the user explicitly asks for an inventory.
- Distinctive: line 82
Use the narrowest useful scope:
- Very specific: line 84
All requirements in .agents/requirements.md, if the user asks for a full trace.
- Distinctive: line 89
Before scanning many repos, tickets, or PRs, state the intended source set and proceed if it matches the request.
- Distinctive: line 93
Use available source systems from project context and user instructions.
- Distinctive: line 107
Do not claim a requirement is complete without linked evidence.
- Very specific: line 108
If a ticket exists but no PR or verification exists, mark the requirement as In progress or Needs verification.
- Very specific: line 109
If a PR merged but no acceptance evidence exists, mark it as Implemented / pending verification.
- Very specific: line 110
If implementation and tests exist but expected PR/check/client evidence was not independently verified, mark it as Implemented / pending …
- Very specific: line 111
If shipped but not client-reviewed, mark it as Shipped / pending review.
- Very specific: line 112
If no ticket/PR exists, mark it as Unlinked.
- Very specific: line 113
If open questions block a requirement, mark it as Blocked and cite the question IDs.
- Very specific: line 178
Use EV-001, EV-002, etc. for verification evidence.
- Very specific: line 179
Use GAP-001, GAP-002, etc.
- Distinctive: line 181
Do not renumber existing trace evidence unless the user explicitly asks.
- Distinctive: line 185
After writing or updating the trace, summarize:
- Very specific: line 197
Read .agents/project-context.md before .agents/requirements.md when available.
- Distinctive: line 201
Do not invent ticket IDs, PRs, commits, checks, or review outcomes.
- Distinctive: line 202
Do not claim acceptance unless the project’s review rule is satisfied.
- Distinctive: line 203
Do not mark code as complete just because a PR exists.
- Very specific: line 204
If evidence conflicts, mark the trace as Needs verification or Blocked and explain the conflict.
- Distinctive: line 207
Keep future polish or out-of-scope work separate from requirement gaps.
- Distinctive: line 218
not mixed with implementation plans or raw logs
- Distinctive: line 222
Use the section headings from the template unless the user requests a different structure.
- Distinctive: line 223
Use markdown tables for trace categories.
- Distinctive: line 224
Keep each row short; link to evidence instead of copying logs.
- Distinctive: line 225
Use stable status labels from this skill.
- Distinctive: line 227
Keep requirement IDs inline in every relevant row.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Execution Trace
You help users connect project requirements to concrete delivery evidence.
This skill is for traceability: requirements to tickets, PRs, commits, checks, releases, demos, review notes, and known gaps. It is not for creating broad project context, extracting decisions, drafting requirements, or implementing code. Start from .agents/project-context.md and .agents/requirements.md when available.
What this skill does
Use this skill to track:
- which requirements have execution artifacts
- which tickets or issues represent the work
- which PRs, commits, or releases implement the work
- what verification evidence exists
- what is blocked, unlinked, or missing verification
- what shipped but still needs review
- what scope guards or non-goals must remain protected
The output is structured markdown, usually at:
.agents/execution-trace.mdDo not assume trace files belong inside a production code repo. They may live in a project workspace above one or more repos.
Workflow
Step 1: Read project context first
Look for:
.agents/project-context.mdIf it exists:
- Read it before tracing execution.
- Identify execution tracker, repository / PR workflow, review rules, source systems, and delivery closeout expectations.
- Follow the project’s stated tracker and repo conventions.
- Do not invent tracker URLs, repo names, PRs, or review rules.
- If the requested skill path is missing but a vendor copy is used, record that as an installation/source gap rather than silently proceeding.
If it does not exist:
- Continue only if the user supplied enough requirement and execution context.
- Do not invent workflow rules.
- Recommend creating project context afterwards if execution trace reveals recurring tracker/repo/review conventions.
Step 2: Read requirements
Look for:
.agents/requirements.mdIf it exists:
- Read it after project context.
- Use functional requirements as the primary trace set.
- Treat non-goals and constraints as scope guards.
- Treat open requirement questions as blockers or gaps, not shipped work.
- Preserve requirement IDs in every trace row.
If it does not exist:
- Continue only if the user supplied specific requirements directly.
- Ask whether requirements should be drafted first if the user only provided decisions, transcript notes, or vague feature descriptions.
- Do not create tickets or PR trace rows without requirement-level source context unless the user explicitly asks for an inventory.
Step 3: Choose the trace scope
Use the narrowest useful scope:
- All requirements in
.agents/requirements.md, if the user asks for a full trace. - A named requirement ID or small set of IDs.
- A named milestone, feature, PR, release, or tracker issue.
- Requirements changed since the last trace update.
Before scanning many repos, tickets, or PRs, state the intended source set and proceed if it matches the request.
Step 4: Gather execution evidence
Use available source systems from project context and user instructions.
Common sources:
| Source | Evidence |
| Linear / Jira / GitHub Issues | Tickets, statuses, assignees, links, comments. |
| GitHub / GitLab | PRs, commits, checks, reviews, release tags. |
| CI / test output | Passing/failing checks and verification notes. |
| Demo / QA notes | Screenshots, demo links, manual verification, client review notes. |
| Requirements file | Requirement IDs, status, blockers, non-goals. |
Rules:
- Do not claim a requirement is complete without linked evidence.
- If a ticket exists but no PR or verification exists, mark the requirement as
In progressorNeeds verification. - If a PR merged but no acceptance evidence exists, mark it as
Implemented / pending verification. - If implementation and tests exist but expected PR/check/client evidence was not independently verified, mark it as
Implemented / pending verificationorNeeds verificationand add a gap for unverified live evidence. - If shipped but not client-reviewed, mark it as
Shipped / pending review. - If no ticket/PR exists, mark it as
Unlinked. - If open questions block a requirement, mark it as
Blockedand cite the question IDs. - Non-goals should be traced as scope guards when relevant, not as implementation tasks.
Step 5: Write or update .agents/execution-trace.md
Use this structure:
# Execution Trace
Status: active
Last updated: YYYY-MM-DD
## Trace sources
| Source | Type | Date / range | Location | Notes |
|---|---|---|---|---|
## Trace status legend
- `Unlinked`: no issue, PR, commit, test, demo, or review evidence found.
- `Planned`: tracker evidence exists, but implementation evidence is not present.
- `In progress`: active tracker, branch, or PR evidence exists.
- `Implemented / pending verification`: implementation evidence exists, but verification or review is incomplete.
- `Needs verification`: evidence is partial, stale, unverified, or missing an expected review/check.
- `Shipped / pending review`: release, demo, or handoff evidence exists, but reviewer/client review is missing.
- `Accepted`: project-defined reviewer/client acceptance evidence exists.
- `Blocked`: open dependency prevents completion.
- `Superseded`: requirement was replaced by a later decision/requirement.
## Requirement trace
| Requirement | Requirement status | Tracker | PR / commit / release | Verification | Trace status | Notes |
|---|---|---|---|---|---|---|
## Scope guards
| Non-goal / constraint | Source | Guardrail | Evidence | Status | Notes |
|---|---|---|---|---|---|
## Verification evidence
| ID | Requirement | Evidence | Result | Date | Notes |
|---|---|---|---|---|---|
## Blockers / gaps
| ID | Requirement | Gap | Owner | Status | Notes |
|---|---|---|---|---|---|
## Local command outputs
Use this section only when local checks were run during the trace. Keep it concise: command, result, date, and a short summary. Do not paste large raw logs.
| Command | Result | Date | Notes |
|---|---|---|---|
## Change log
| Date | Change | Source |
|---|---|---|Evidence ID format:
- Use
EV-001,EV-002, etc. for verification evidence. - Use
GAP-001,GAP-002, etc. for blockers/gaps. - Preserve existing IDs when updating a file.
- Do not renumber existing trace evidence unless the user explicitly asks.
Step 6: Report the trace cutline
After writing or updating the trace, summarize:
- requirements traced
- requirements with no linked execution
- implemented items needing verification
- blockers / gaps
- shipped items pending review
- accepted items with evidence
- recommended next action, if useful
Source handling rules
- Read
.agents/project-context.mdbefore.agents/requirements.mdwhen available. - Preserve requirement IDs in every trace row.
- Preserve tracker IDs, PR numbers, commit SHAs, check names, release tags, and demo/review links when available.
- Distinguish local git evidence from live PR/check verification. PR numbers found in merge commits or tracker attachments are not the same as independently verified PR content/check results.
- Do not invent ticket IDs, PRs, commits, checks, or review outcomes.
- Do not claim acceptance unless the project’s review rule is satisfied.
- Do not mark code as complete just because a PR exists.
- If evidence conflicts, mark the trace as
Needs verificationorBlockedand explain the conflict. - Be precise when citing schema/test evidence. If a test rejects an unsupported node type, do not word it as rejecting a similarly named valid payload or field unless the evidence proves that exact claim.
- Assign source-verification gaps to the operator/system that can verify them, not automatically to a person named in the project context.
- Keep future polish or out-of-scope work separate from requirement gaps.
Output standard
A good .agents/execution-trace.md is:
- compact enough to scan
- explicit about evidence and gaps
- honest about verification status
- linked to requirements, tickets, PRs, and checks when available
- clear about what shipped, what is blocked, and what still needs review
- not mixed with implementation plans or raw logs
Formatting rules:
- Use the section headings from the template unless the user requests a different structure.
- Use markdown tables for trace categories.
- Keep each row short; link to evidence instead of copying logs.
- Use stable status labels from this skill.
- Preserve the requirement's own status as written, but prefer unambiguous requirement statuses such as
Requirement readyover bareReadywhen updating requirements as part of trace hygiene. - Keep requirement IDs inline in every relevant row.
Common pitfalls
- Claiming completion from a ticket status alone.
- Claiming acceptance without reviewer/client evidence.
- Treating merged PRs as verified requirements.
- Treating locally observed PR numbers as live GitHub verification.
- Using broad evidence wording that accidentally rules out valid payloads, fields, or future scope.
- Losing requirement IDs when summarizing delivery.
- Mixing future polish with blocked requirement gaps.
- Turning non-goals into implementation tasks.
- Copying large CI logs or raw PR text into the trace file.
Verification checklist
Before finishing:
.agents/project-context.mdwas read when available..agents/requirements.mdwas read when available.- Requirement IDs are preserved in trace rows.
- Tracker/PR/commit/check evidence is linked when available.
- Completion is not claimed without evidence.
- Client/reviewer acceptance is not claimed without review evidence.
- Live tracker/PR/check verification gaps are explicit when only local git or local tests were available.
- Scope guard evidence is worded narrowly enough not to reject valid adjacent schema/payload concepts.
- Blockers and gaps are visible.
- Existing evidence IDs were preserved on update.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

