work-record
Use when you finished work on a tracker task and it must be recorded in the workspace through a merge request.
- License 许可
- MIT
- 最近更新
- 2026-10-30
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- work-record
- description
- Use when you finished work on a tracker task and it must be recorded in the workspace through a merge request.
03 SKILL.md 正文
Record finished work
Steps
- Go to the workspace root: the nearest directory, walking up from where you are, where
test -f .agents/kit.jsonsucceeds. Run every command below from there. - Ask the person for the task id. Below the id is
<ID>. Check it:- Read
id_patternfromtracker/tracker.json. JSON doubles every backslash, so\\din the file means\d. - Rewrite the pattern for
grep -E: write every\das[0-9], becausegrep -Edoes not know\d. - Run
printf '%s\n' '<ID>' | grep -Ex '<rewritten pattern>'. The-xmakes the whole id match, not a part of it. - If it prints nothing, stop and ask again.
- Read
- Read
.local/drafts/<ID>.md. If it does not exist, ask the person four questions: what changed, which decisions were taken, what is still open, and what was verified. Wait for the answers before going on. - Find the workspace default branch: run
git symbolic-ref --short refs/remotes/origin/HEADand remove theorigin/prefix; when the command fails, usemain. Call it<default>. Then rungit fetch origin. - Read the manifest of the default branch: run
git show origin/<default>:repos.json. Below, "the manifest" is this output, never therepos.jsonfile of the current branch: the record is checked against the default branch, and a repository added only on an unmerged branch would fail thework-recordcheck. Collect commits. For each entry inrepositoriesof the manifest whose directoryrepos/<name>exists, with<default_branch>from the entry:- Run
git -C repos/<name> fetch --prune. - Run
git -C repos/<name> for-each-ref --format='%(refname:short)' refs/heads refs/remotes | grep -E '(^|[^A-Za-z0-9])<ID>([^0-9]|$)'. Each printed line is one<branch>, used as printed. The grep keeps only names where<ID>is a whole token, soTASK-1does not matchfeat/TASK-10-y. - For every
<branch>, rungit -C repos/<name> log --format=%H origin/<default_branch>..<branch>. - Run
git -C repos/<name> log --format=%H -E --grep='<ID>([^0-9]|$)' origin/<default_branch>to find work that is already merged. - Write each sha as
<name>@<sha>. Keep each value once, in the order found. - A repository with at least one sha goes into
repos.
- Run
- If no repository gave a sha, ask the person which repositories and branches hold the work, and repeat step 5 for them. A repository that is not in the manifest cannot go into
repos; tell the person it must be merged into<default>first. - Collect merge requests. For each repository in
repos, look at itsforgein the manifest:gitlab: ifcommand -v glabandglab auth statusboth succeed, runglab mr list --search "<ID>" --all --output jsoninsiderepos/<name>and take everyweb_urlvalue that contains/-/merge_requests/(the otherweb_urlvalues are user profiles). Otherwise addglabto themissinglist.github: ifcommand -v ghandgh auth statusboth succeed, rungh pr list --search "<ID>" --state all --json url --jq ".[].url"insiderepos/<name>and take every printed URL. Otherwise addghto themissinglist.git: there is no merge request data; add nothing.- Keep each URL once, in the order found. Keep each name in
missingonce.
- Run
git status --porcelain --untracked-files=no. If it prints anything, stop and tell the person: the workspace has uncommitted tracked changes. Commit nothing. - If
git rev-parse --verify --quiet work/<ID>orgit rev-parse --verify --quiet origin/work/<ID>succeeds, the branch already exists:- For each of
work/<ID>andorigin/work/<ID>that exists, rungit diff --name-only origin/<default>...<that branch>. - If any printed path does not start with
work/<ID>/, stop and tell the person which paths they are. Commit nothing. - If
origin/work/<ID>exists, the branch is already pushed. Its commits must never be rewritten. Remember this for steps 14 and 15. Then:- When
git rev-parse --verify --quiet work/<ID>succeeds, rungit switch work/<ID>, thengit branch --set-upstream-to=origin/work/<ID>. - Otherwise run
git switch --track origin/work/<ID>. - Run
git pull --ff-only. If it fails, stop and tell the person that the local and pushedwork/<ID>differ. Commit nothing.
- When
- If only the local
work/<ID>exists, rungit switch work/<ID>. - Bring the branch up to date: run
GIT_EDITOR=true git merge --no-edit origin/<default>. The branch may predate a repository merged into<default>; after the merge itsrepos.jsonequals the manifest from step 5, which step 12 checks the record against. The branch changes onlywork/<ID>/, so the merge is clean. On a conflict, rungit diff --name-only --diff-filter=Uto list the files, thengit merge --abort, show the two versions as step 14 describes and stop. Commit nothing. - Skip step 10.
- For each of
- Otherwise run, one by one:
git switch <default>git pull --ff-onlygit switch -c work/<ID>
- Write
work/<ID>/record.mdfrom.agents/templates/work-record.md:- Frontmatter
task: <ID>. repos,merge_requestsandcommitsas block lists: the linekey:, then one line- valueper value. Writekey: []when the list is empty.- Add
story:only when the person names a story. Addcontract:orconsumed_contract:only when the person gives them, askey:then linessub: value. - Replace
<one-line summary>in the title with one line about the work. - Fill
## Changed,## Decisions,## Open questionsand## Verificationfrom the draft or the answers. Write "None." in a section with nothing to say. - Write a stand as a link to its key,
[stand:<name>](../../environments.json), never as an address. - Never link into
.local/.
- Frontmatter
- If
command -v python3succeeds, check the record:- Run
python3 tools/generate.py, thenpython3 tools/check.py. Each finding is a linepath:line rule message. - If a finding has the path
work/<ID>/record.md, fix it in that file and run both commands again. - Exception: a
work-recordfinding "repository X is not in repos.json" for a repository X taken from the manifest in step 5 is never fixed by removing X fromrepos. Stop and tell the person the finding. Commit nothing. - Change no other file. When no finding has the path
work/<ID>/record.md, stop repeating. Remember the findings that are left for the report. - Otherwise, when
python3is missing, remember the linecheck not run: python3 missing.
- Run
- Commit: run
git add work/<ID>/, thengit commit -m "docs(work): record <ID>". - Update from the default branch:
- If step 9 found
origin/work/<ID>, runGIT_EDITOR=true git merge --no-edit origin/<default>. On a conflict, rungit diff --name-only --diff-filter=Uto list the files, thengit merge --abort. - Otherwise run
git pull --rebase origin <default>. On a conflict, rungit diff --name-only --diff-filter=Uto list the files, thengit rebase --abort. - A conflict means someone else changed
work/<ID>/. For each listed<file>, show the person two versions with their labels: "default branch" is the output ofgit show origin/<default>:<file>, and "your branch" is the output ofgit show work/<ID>:<file>. Then stop.
- If step 9 found
- Push and open the merge request by
params.forgein.agents/kit.json:gitlab: rungit push -u origin work/<ID> -o merge_request.create -o merge_request.title="Work record <ID>".github: rungit push -u origin work/<ID>, thengh pr create --title "Work record <ID>" --body "work/<ID>/record.md". Ifghis missing or the command fails, print its error and ask the person to open the pull request for branchwork/<ID>.git: rungit push -u origin work/<ID>, print the branch namework/<ID>and ask the person to open the merge request.- Never push with
--forceor--force-with-lease.
- If the push is rejected, print the error and these commands to finish by hand, then stop:
- When step 9 found
origin/work/<ID>:git pull --no-rebase --no-edit origin work/<ID>, thenGIT_EDITOR=true git merge --no-edit origin/<default>. - Otherwise:
git pull --rebase origin <default>. After fixing a conflict, rungit add <file>, thenGIT_EDITOR=true git rebase --continue. - Then the push for the forge:
gitlab:git push -u origin work/<ID> -o merge_request.create -o merge_request.title="Work record <ID>"github:git push -u origin work/<ID>, thengh pr create --title "Work record <ID>" --body "work/<ID>/record.md"git:git push -u origin work/<ID>, then open the merge request for branchwork/<ID>in the forge web page.
- When step 9 found
- Report to the person:
- the record path
work/<ID>/record.md; - the branch
work/<ID>; - the merge request link, or the instruction to open it;
missing: <names from the missing list, joined with ", ">, ormissing: none;- the check findings left in other files, if any;
- as the last line, the check result, or
check not run: python3 missing.
- the record path
Example record
work/TASK-1/record.md for work in repository demo-bff with one commit and no merge request data:
---
task: TASK-1
repos:
- demo-bff
merge_requests: []
commits:
- demo-bff@2c0efd7072c42fb1df4dce53f4c284baf338a035
---
# TASK-1: Show the card limit on the payment screen
## Changed
demo-bff: the `/payments/screen` response now has a `card_limit` field read from the limits service.
## Decisions
The limit is cached for 60 seconds per card to keep the screen fast; the limits service allows this staleness.
## Open questions
None.
## Verification
Unit tests pass in demo-bff. The payment screen was opened on [stand:test](../../environments.json) and showed the limit for a test card.
Without Python
- Skip
python3 tools/generate.pyandpython3 tools/check.pyin step 12. - A work record changes no generated file, so no recipe is needed.
- End the report with the line:
check not run: python3 missing
04 同仓库更多 Skills
verify
Use when a change in __SERVICE__ must be checked before review
work-record
Use when you finished work on a tracker task and it must be recorded in the workspace through a merge request.
task-new
Use to create one story in a stream from the stream profile's story template, link it from its scope screens and open a merge request.
task-decompose
Use to split a stream at the decomposition stage into stories - list scope screens without a story, create the accepted stories and close the stage through a merge request.
task-context
Use to gather the context of a story key or a tracker id - its story, stream stage, scope screens, repositories, decisions, mockups and work records.
repos-sync
Use to update clones of your repositories under repos/ and see their branch, lag and uncommitted changes.