lab-knowledge

Files (9)

• SKILL.md
• acceptance.md · references/
• claim-page.md · references/
• library.md · references/
• publishing.md · references/
• record-contract.md · references/
• what-is-a-claim.md · references/
• writing-in-git.md · references/
• lab_run.py · scripts/

SKILL.md (first lines)

# Lab Knowledge

Read the base from the local clone of the work (`grep`, `git log`, `git show`); there is no reading server any more, it was removed on 05-10-2026 because nobody used it. Personal Obsidian notes, agent history
and the laboratory's shared records have different owners and purposes.

## Find what the laboratory knows

**Search the clone, with `grep` and `git log`.** There is no search service: the one that
existed lived on Postgres embeddings and was deleted on 07-10-2026 together with its base.
A work is a git repository, so `grep -rn "<term>" <work>/claims/` and `git log -S"<number>"`
answer faster than any index, and they never return a stale snapshot. Papers of the library
are files too: `<theme>/literature/` holds one page per paper, named by its citation key.

For the laboratory's own knowledge, **read the clone**: `grep` and `git log` over
`<work>/claims/`, which is checked out locally. That is faster than any search call and it is
the same bytes the reviewer sees. There is no typed index and no read API: the directory
listing of `claims/` is the index, and the first line of each `README.md` is the claim.

A closed task is not a confirmed claim. Verify changeable facts against their current source
before reporting them as current. A read-only question must not cause writes.

Return the supporting public codes, shared links, and any uncertainty. Do not publish local
paths, private transcripts, or credentials as provenance.

## Start with the manuscript and the code, not with the claims

A work that has a paper and a training repository brings them **into the work itself**, as
submodules, before a single claim is written:

```bash
git submodule add https://git.overleaf.com/<id> paper/<work>
git submodule add <git url of the training code> code/<name>
git commit -F -        # say what was connected and where it came from
```

The repository then stores a pointer, `lab here` brings the text, and both are named in the
README in backticks. They are not gitignored and not pasted as a link in prose: a reader, a
gate and an agent all need to open them, not to be told they exist.

**Why this comes first.** Claims, runs and series are then derived from material that is in
hand. Every number copied out of the paper carries the address it came from — the table or
figure label, not the word «рукопись» — and that address can be opened and checked on the
spot. Measured 13-10-2026 on `spectral-wd`: with the manuscript pulled, four of its numbers
turned out not to be in the paper's tables at all, one was attributed to a 124M model where
the paper's caption says 257M, and the claim «the manuscript has no experiments» proved
false — it had been written from an older version someone had sent. None of that is visible
while `paper/` is an empty folder.

**Before writing anything, check they are actually there**, because an unpulled submodule
looks exactly like an absent one:

```bash
git submodule update --init --recursive
find paper -name '*.tex' | head        # empty output means not pulled, not «no manuscript»
```

If the work has no paper or no code yet, say so in the README in one line and name who has
them. That is a debt with an owner, not a silence.

## Существующий проект → работа

A project that already lives as a folder — manuscript, logs, notes, code, call transcripts —
becomes a work in two halves. **Knowledge goes to GitLab as `claims/` by merge request.
Personal material stays on the machine, copied into the local-only folders of the work's own
clone in the tree**, so the owner's `~/brainlab` looks the same for this work as for every
other one. One clone, in the tree; never a clone in `~/.cache`, never a token in a URL.

The layout of a work (handbook `tools/gitlab.md`, «Как разложена работа»): what lies in a
folder itself is shared and goes to GitLab; its `drafts/`, `local/` or `raw/` subfolder stays
on the machine.

| from the old project | into the work | in GitLab |
|---|---|---|
| claims, runs, series, derivations, figures | `claims/H-…/` | yes, by merge request |
| manuscript (Overleaf) | `paper/<work>` submodule | yes |
| training code | `code/<name>` submodule | yes |
| poster, posts | `socials/` | yes |
| what a call decided | `calls/<DD-MM-YYYY>.md` | yes |
| notes, plans, hypotheses, tool settings | `notes/` | no |
| diary | `daily/` | no |
| raw logs, dumps, notebooks, result pictures | `runs/` (root shelf) | no |
| old manuscripts and editions | `paper/drafts/` | no |
| working code, local clones | `code/local/` | no |
| recordings and transcripts | `calls/raw/` | no |

The flow:

1. **The work exists in GitLab**, created empty and `internal` in its theme's group (the
   `create-project` skill), with a README whose `**Ведут**` line names the lead.
2. **`lab here <work>`** puts the clone at `~/brainlab/<direction>/<theme>/<work>`, closes
   `notes/`, `daily/`, `/runs/`, `paper/drafts/`, `code/local/`, `calls/raw/` in
   `.git/info/exclude`, and sets the push options: `merge_request.create` and
   `merge_request.assign=<lead from Ведут>`. Run it again after the README with `Ведут` is on
   `main` if the assignee was missing.
3. **Connect the manuscript and the code** as submodules (the section above).
4. **Copy the personal material** into the local-only folders. Look at the plan first:

   ```bash
   python3 ~/brainlab/agents/services/scripts/claims/copy_personal.py <project folder> <clone>
   python3 ~/brainlab/agents/services/scripts/claims/copy_personal.py <project folder> <clone> --apply
   ```

   It copies and never deletes the source, never overwrites a file already in the clone,
   refuses to run while any destination is not excluded from git, and lists what it could
   not classify — that is decided by hand, not guessed.
5. **Knowledge into `claims/` by merge request.** By hand: branch, claim pages, `git commit -F
   -`, `git push`. Or the runner, which does steps 2 and 4 itself and then builds claims,
   series, runs, proofs and figures from the manuscript (it spends model calls):

   ```bash
   ~/brainlab/agents/services/scripts/claims/work-to-repo-git.sh <work> <theme> \
       "<project folder>" ["<manuscript .tex>"]
   ```

   It works on the branch `work/razbor` of the tree clone, starts only from a clean `main`
   (or resumes its own branch), pushes only when `sweep.py` finds zero remarks, and exits
   non-zero when the push or the merge request fails.
6. **Check** that nothing personal is staged (`git status` lists none of the local-only
   folders) and read `lab checks`.

From Vepricov/claude-brainlab, MIT.

More from Vepricov/claude-brainlab