worklog

name

worklog

description

Issue-led atomic work logging. Use whenever the user says "worklog" or asks to run, apply, start, maintain, update, summarize, or close a worklog; also use for issue-led development, master or umbrella issue tracking, one-issue-per-bug/feature/change workflows, atomic issue-scoped commits, GitHub issue comment journals, closeout summaries, durable engineering ledgers, and making sure no compatibility, migration, cleanup, or residual-risk work is left hanging without an issue.

Worklog

Use GitHub issues as the durable source of truth for a body of work. Keep a master issue for the overall effort, a separate child issue for each bug, feature, experiment, or change, atomic commits for each logical unit, and issue comments as the running engineering ledger.

Core Contract

• Treat the master issue as the project ledger: scope, child issue index, current status, unresolved decisions, and final rollup.
• Treat child issues as executable work units: one bug, feature, experiment, refactor, docs change, or operational change per issue.
• Keep commits atomic and issue-scoped. Prefer one coherent commit per child issue or per independently reviewable step inside that issue.
• Record important observations, commands, failures, design decisions, implementation notes, artifacts, verification, and residual risk as comments on the child issue.
• Close a child issue only after posting a detailed closeout comment with what changed, evidence, tests, commit refs, and remaining follow-up.
• Update the master issue when child issues are opened, materially change direction, resolve, or create follow-up work.
• Do not leave hanging work implicit. If any compatibility shim, migration, cleanup, temporary fallback, unresolved verification, operational risk, or "duct tape" remains, create or link a follow-up issue before saying the work is done.

Before Touching GitHub

Verify the actual repo and target issue surface:

git remote -v
gh repo view --json nameWithOwner,url
gh issue list --state all --limit 50

If the repo target is ambiguous, private/public boundaries are unclear, or the action would post to someone else's upstream repo, ask for confirmation before creating, commenting, closing, or editing issues. If a user fork exists and the user did not ask to post upstream, prefer the user's repo/fork.

Starting A Worklog

1. Inspect existing issues before creating new ones.
2. Reuse an existing master issue if it clearly owns the effort.
3. Create a new master issue when no durable parent exists.
4. For every distinct work item, create or identify a child issue and link it from the master issue.
5. If the task already has code changes in progress, inspect git status and diffs before deciding issue boundaries.

Master issue body should include:

## Goal
<overall goal>

## Child issues
- [ ] #N - <title>

## Current state
<short status>

## Operating rule
Each bug, feature, experiment, or change gets its own issue. Work is recorded in issue comments. Commits stay atomic and issue-scoped. Child issues close with a detailed closeout; this master issue receives concise rollups.

Child issue body should include:

## Scope
<one concrete unit of work>

## Why
<user-visible or engineering rationale>

## Acceptance criteria
- <verifiable outcome>

## Notes
Tracked under #<master-issue>.

During Work

Post child issue comments at durable milestones, not for every minor thought:

• Initial diagnosis: what was observed, relevant files/issues, and the immediate plan.
• Important discoveries: new facts that change scope, risk, or approach.
• Implementation progress: atomic change made, files touched, and commit ref if available.
• Verification: exact commands run, pass/fail result, relevant output summary, and artifacts.
• Blockers: what failed, why it matters, and the proposed next move.
• Hardware profile gate for paid or long accelerator runs: before full launch, record the realistic smoke sweep, throughput, memory, estimated MFU, chosen profile, and any user-approved efficiency tradeoff.

Use comments as a journal another engineer could resume from. Include exact commands and paths when they are material. Avoid vague status updates that do not preserve new information.

Atomic Commits

Before committing, inspect status and diffs:

git status --short
git diff

Stage narrowly. Do not include unrelated user changes. Commit messages should name the issue and the reason:

Fix share receiver timeout handling (#42)

Preserve captures when enrichment exceeds the fast-path budget so mobile sends
return promptly while background processing continues.

If one diff covers multiple child issues, split it before committing when practical. If splitting would create churn or risk, explain the coupling in the issue comment and commit body.

Closing A Child Issue

Before closing, run a residual-work audit. Look specifically for compatibility aliases, temporary configs, local-only workarounds, migration gaps, unverified runtime surfaces, missing cleanup, security loosenings, flaky tests, manual steps, and known risks. If any remain, open or link issue(s) for them first.

Post a final comment before closing:

## Resolution
<what changed>

## Evidence
- Commit(s): <hashes or PR>
- Verification: <commands and results>
- Artifacts: <links or paths if relevant>

## Follow-up
<none, or linked issue numbers>

Then close the issue. If follow-up work remains, open or link separate child issues instead of hiding incomplete work inside a closed issue. Only write none when the residual-work audit found no remaining tracked work.

Updating The Master Issue

When a child issue closes, post a concise master comment:

Resolved #N: <one-sentence outcome>.

Evidence: <commit/test/artifact summary>.
Follow-up: <none or linked issue numbers>.

Keep the master issue useful for scanning. Detailed logs live on child issues; master comments are rollups and routing.

If GitHub Is Not Available

If gh is unavailable, authentication fails, or network access blocks issue updates, continue the workflow locally:

• Draft the exact issue body or comment text in the response.
• Preserve the child/master issue structure.
• Do not claim anything was posted.
• Tell the user what command or action remains.