clock-in

Files (2)

• SKILL.md
• progress.adoc · templates/

SKILL.md (first lines)

# Clock In

## Purpose

Resume work without depending on what anyone remembers.

A session that starts by asking "where were we?" gets an answer built from
memory. This skill starts from the repository instead, and only then asks the
one question the repository cannot answer: which topic to work on.

The counterpart is `skills/clock-out/SKILL.md`.

## The two layers

A working day has two durable records, and they belong to different owners:

| Layer | Owner | Holds |
|---|---|---|
| Project | the repository being worked in | topic plans, project diary, issues, branches |
| Private | the user's own journal repository | the cross-project day, the daily focus, personal threads |

**Both layers are always considered.** A clock-in that only touches one of them
is incomplete, and it must say which one it skipped and why. A layer that is
absent is *recorded as absent*, never invented.

## Session lead

Exactly one skill leads an invocation. The lead does the orchestration; anything
it invokes runs **delegated** and does not orchestrate back.

- Invoked inside a project that uses this toolkit, **this skill leads**. It
  drives the project layer, then hands over to the private journal's own
  clock-in skill in delegated mode.
- Invoked outside such a project — the user says "clock in" with no project in
  context — the private journal's clock-in skill leads on its own. This skill is
  not involved, and the private journal skill must work without it.
- A delegated skill never sweeps other repositories and never delegates back.
  Without this rule the two layers call each other in a loop.

The multi-project view belongs to the private layer. This skill orients **one**
repository: the one it was invoked in.

## Never delegate to yourself

Every delegation in this skill finds its target by path, not by identity, and
three of those paths resolve back to this file:

- Inside the toolkit itself, `skills/clock-in/SKILL.md` "in the repository being
  worked in" **is** this file.
- A project that installed the toolkit's skills into its own `skills/` reaches
  this file through a symlink that looks project-local.
- A private journal bound to a repository whose clock skill defers back upward —
  the normal shape of a project delta — arrives here again by way of the
  binding.

So: **resolve every delegation target to its real path, following symlinks, and
compare it with the file you are executing.** Same file, and you are already the
delegate: do not delegate, and use the default layout instead.

The session lead rule does not cover this. It governs the loop *between* the two
layers and assumes the two skills are different files; self-delegation happens
*inside* one layer, where that rule never fires.

## Workflow

**1. Establish the project state before asking anything.**

```sh
git status --short && git branch --show-current
git log --oneline -5
gh pr list --state open
gh issue list --state open --limit 20
```

Note anything that contradicts what the topic files will claim. Uncommitted
work, a branch that is not the base branch, an open pull request — these are
facts about where the last session stopped, and they outrank any file.

Every one of those four commands describes the *current* branch, plus whatever
branches happen to carry an open pull request. A branch with commits and no pull
request is invisible to all four, and that is the ordinary shape of work in
progress. So establish the state of the whole repository as well:

The enumeration names the base branch rather than assuming it, prints how far
each ref is ahead of and behind it, and ends in one verdict. Listing refs is not
the point — divergence from the base is, and a list of names still leaves the
comparison to whoever reads it.

```sh
gap=""

base=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD) ||
  { echo "SWEEP: BLOCKED — UNAVAILABLE:base (run git remote set-head origin --auto once)"; exit 1; }
git fetch --quiet --prune origin ||
  { echo "SWEEP: BLOCKED — UNAVAILABLE:fetch"; exit 1; }
refs=$(git for-each-ref --format='%(refname:short)' refs/heads refs/remotes/origin) ||
  { echo "SWEEP: BLOCKED — UNAVAILABLE:refs"; exit 1; }
names=$(printf '%s\n' "$refs" | sed 's|^origin/||' | sort -u) ||
  { echo "SWEEP: BLOCKED — UNAVAILABLE:dedup"; exit 1; }

report_ref() {
  if ! counts=$(git rev-list --left-right --count "$base...$1" 2>/dev/null); then
    gap="$gap UNAVAILABLE:divergence($1)"; return
  fi
  if ! newest=$(git log -1 --format=%cs "$1" 2>/dev/null); then
    gap="$gap UNAVAILABLE:date($1)"; return
  fi
  echo "$1: $(echo "$counts" | awk '{print $2}') ahead," \
       "$(echo "$counts" | awk '{print $1}') behind $base, newest $newest"
}

for name in $names; do
  case "$name" in "${base#origin/}" | origin | HEAD) continue ;; esac
  git show-ref --verify --quiet "refs/heads/$name" && has_local=yes || has_local=no
  git show-ref --verify --quiet "refs/remotes/origin/$name" && has_remote=yes || has_remote=no

  if [ "$has_local" = yes ] && [ "$has_remote" = yes ]; then
    git merge-base --is-ancestor "origin/$name" "$name" 2>/dev/null
    case $? in

From docs-as-code-toolkit/architecture-knowledge-toolkit, MIT.

More from docs-as-code-toolkit/architecture-knowledge-toolkit