describing-changes

Files (1)

• SKILL.md

SKILL.md (first lines)

Show the shape of a change for a reader who will never open the code: pseudocode, never real source.

Use the repo's ubiquitous language: the names it already gives each thing.

## Process

1. List every change — new and modified models, modules, flows, and files — and group them by area.

   Done when every change is accounted for.

2. Pick the smallest set of views that makes the changes clear. See [Views](#views).

   Done when every change appears in a view.

3. Lead each view with one sentence that says what it shows. When there is more than one area, put each area under its own heading at the level the surrounding document uses. Order the views so the story is easiest to follow — for example, establish a model before the flow that uses it.

   Done when every view has its sentence and no view depends on one that comes after it.

4. Before returning, load the removing-ai-tells skill and apply it to the prose. Keep each view's sentence.

   Done when the prose is cleaned of AI tells and every view is unchanged.

## Notation

Strip the language syntax and keep the real names of functions, types, and files.

Give variables descriptive names, as you would in real code: `user`, not `u`.

A model reads:

```text
Session
  prompt: string
```

Write primitives in lowercase (`string | number`) and type aliases in PascalCase (`SessionStatus | AgentKind`).

Show a nested object by indenting its fields under the field that holds it:

```text
Session
  prompt: string
  agent?:
    kind: AgentKind
    model: string
```

A function reads:

```text
createSession({ prompt: string }): Session

updateSession({
  prompt: string
  status: SessionStatus
}): Session
```

Put parameters on one line when there is one, and one per line when there are two or more.

Write `return` in every function body that returns a value. The return type says what kind of value comes back; the `return` says which value. A `void` function needs no `return`.

Separate the steps of a function body with a blank line: setup, each branch, and the `return`. Put a blank line between functions in the same view.

```text
createSession({ prompt: string }): Session
  if prompt is empty
    throw

  agent = pickAgent({ prompt })

  return
    prompt = prompt
    agent = agent
    status = pending
```

Group variants of one operation under a shared name:

```text
getSession
  fromId({ id: uuid }): Session
  fromPrompt({ prompt: string }): Session
```

Keep only the calls, files, fields, states, and boundaries the reader needs. Omit everything else.

When a view comes from one file, put the file path in inline code on its own line above the code block:

`src/sessions/createSession.ts`

```text
createSession({ prompt: string }): Session
```

Use `#` comments inside a view only for boundaries that change within it, such as packages in a component tree.

Tag the code block with the language the code will be written in, even though the content is pseudocode, so it renders with syntax colour. A TypeScript model reads:

```typescript
Session
  prompt: string
```

Use `text` only for views with no source language, such as call trees, component trees, and file trees. Diagrams stay `mermaid` and diffs stay `diff`.

When a model includes another type's fields, write it as `& TypeName` above its own fields, one per line. List fields taken from part of a type as normal fields. Write a union the same way, with one `| TypeName` per line.

```typescript
AgentSession
  & Session
  & Timestamps
  agent: AgentKind
  logs: string[]

SessionEvent
  | SessionStarted
  | SessionFinished
  | SessionFailed

From supagetto/README.ai, MIT.

More from supagetto/README.ai