jj-describe

Files (1)

• SKILL.md

SKILL.md (first lines)

Write a description for the current `jj` commit.

# Current commit

```!
jj show --git
```

# Recent descriptions

```!
jj log -r 'ancestors(@-, 10)' --no-graph -T 'description'
```

# Recent descriptions for the changed files

```!
jj log -r "latest(::@- & files($(jj diff -r @ --name-only | sed 's/.*/\"&\"/' | paste -sd'|' -)), 10)" --no-graph -T 'description.first_line() ++ "\n"'
```

Arguments: $ARGUMENTS

# Principles

- Explain why the change was made, because the diff already shows what changed
- Write the summary line so it completes the sentence "If applied, this commit
  will ...": 50 characters preferred and 72 at most, no trailing period. Name
  the fix rather than the problem it fixes. Avoid a filename or a generic phrase
  such as "fix bug", "refactor", or "cleanups"
- Match the prefix style, capitalization, and detail of the previous commits to
  the same files, falling back to the recent descriptions above where those
  commits disagree. Without a consistent convention, write `<topic>: <summary>`,
  where the topic is the module, directory, or command the change touches
- Add a body only when the summary leaves something unexplained: the status quo
  the change corrects, the motivation, how the change works, a rejected
  alternative, a known limitation, or a consequence a reader would miss. Wrap it
  at 72 columns, separated from the summary by a blank line
- State the status quo in the present tense and without "Currently", because a
  description is read against the code before the change: "the parser stops at
  the first error"
- Explain how the change works only where the diff leaves it unclear, in plain
  words and at the level of the feature rather than the code
- Mention a rejected alternative only when you tried it, rather than only
  considered it, and a reader would ask why you didn't take it
- Back a claim about performance or size with the measurements before and after
  the change
- Leave out what the diff shows, such as which files and functions changed and
  that the tests were updated
- Leave out how the commit came about, such as what was tried first, what it was
  rebased onto, and what happened in the session that wrote it
- Describe the commit's own change, not the stack around it
- Keep the description readable on its own. Summarize an issue or a linked page
  rather than pointing at it, and name another commit by its change ID and its
  summary line rather than the ID alone

# Workflow

1. Read the diff above. If the commit is empty, tell the user and stop
2. Treat any existing description as the author's intent: keep what it states
   and extend it to cover the rest of the diff, unless the arguments ask for a
   replacement
3. Read the descriptions for the changed files above to see which convention
   previous commits to these files followed
4. Work out why the change was made. Read the surrounding code when the diff
   alone doesn't explain it. Prefer the arguments over your own inference
5. Set the description with `jj describe -m '<summary>' -m '<body>'`, passing a
   second `-m` only for a body. Each `-m` becomes its own paragraph
6. Show the result with `jj log -r @ --no-graph -T 'description'`

# Fixing mistakes

Rerunning `jj describe` replaces the whole description. To recover the previous
one, find the describe operation with `jj op log` and revert it with
`jj undo <operation>`.

From TomerAberbach/claude-config, MIT.

More from TomerAberbach/claude-config