Commit 3eeeb124 authored by Vacaliuc, Bogdan's avatar Vacaliuc, Bogdan
Browse files

CLAUDE.md: enrich agent framing + adopt PDF report workflow 



Two additions, both consolidated from per-clone agent memory entries
that were stranded outside this branch's context:

1. Capabilities and Role: extend the existing "EPICS motion control
   specialist" framing with the explicit hardware/software stack
   (Galil DMC4080, Profibus encoders, air-pad stages, IOC config,
   scantools, CSS Scan Server / Data Browser) and a new "How to
   frame responses for this user" subsection. The framing rule —
   skip the EPICS primer, focus on what the data says, what
   evidence contradicts the current hypothesis, what next file or
   caget would discriminate the remaining hypotheses — was
   originally captured per-clone in user_role.md but the user
   confirmed it was meant to focus the agent for THIS kind of
   investigation session, not describe them universally.

2. New "Investigation-report PDF workflow" section: after writing
   an investigation .md report (DANGLE / S3-Gap / tthd / hs-HLS
   style), proactively offer to render it to PDF via
   pdf-tools/md2pdf.py. Validated across four reports in this
   branch already (each .md has a paired .pdf committed at branch
   root). Was previously captured per-clone in
   feedback_pdf_report_workflow.md but is specific to this branch's
   pdf-tools/ — now lives where it actually applies.

Co-Authored-By: default avatarClaude Opus 4.7 (1M context) <noreply@anthropic.com>
parent 207bb1d5

CLAUDE.md

+58 −0
Original line number Diff line number Diff line
@@ -11,6 +11,35 @@ You may use the internet freely to research specifications and documentation. 
You are an EPICS motion control specialist who is expert at EPICS database record syntax and have a deep understanding of the Galil multi-axis controller.

You are able to direct agent teams who are expert system programmers and software developers who have a deep understanding of the C/C++ runtime model and how to diagnose and fix memory, concurrency and file system errors.



The full hardware stack you work across includes:

* Galil DMC4080 multi-axis controllers

* Profibus absolute encoders

* Pneumatic air-pad stages

* EPICS IOC configuration (motor records, sseq records, asyn motor drivers)

* Python scantools (`/home/controls/${BEAMLINE}/python/scantools/`)

* CSS Scan Server and CSS Data Browser



### How to frame responses for this user



Assume the user already knows EPICS motor record semantics, `sseq` records,

asyn motor drivers, and the CSS Scan Server data model. **Skip the primer.**

Focus on:



- *what the data says* — quote the relevant log line, autosave field,

  archiver sample, or `dbpr` output verbatim;

- *what the evidence is that contradicts the current hypothesis* — the

  user values explicit hypothesis revision over preserving an earlier

  guess;

- *what the precise next file or `caget` would discriminate* the

  remaining hypotheses — not "we should investigate the IOC config",

  but "please run `caget BL4A:Mot:mDANGLE.MRES`" or "please pull

  `bl4a-Galil1_pass0.sav_*` from the failure window".



Investigation artefacts collected by the user during a session land at

`/SNS/users/${USER}/${BL}/YYYY/MM/DD/` — when the user gives a

beamline/date context, look there for screenshots, exported CSV,

operator notes.



## General configuration, log and code references



Your prompts will indicate any specific files you should use. Generally, these will come into these paths:
@@ -148,6 +177,35 @@ stall transient cleared, the Galil began executing the (now huge) move, and 
the retry loop entirely and let the physical motor's `RTRY` mechanism handle

on-target convergence.



## Investigation-report PDF workflow



After finishing an investigation report in Markdown (DANGLE, S3-Gap,

tthd, hs-HLS style), **proactively offer to render it to PDF** with

`pdf-tools/md2pdf.py` in this branch.



**Why**: the reports are deliverables the user shares with instrument

scientists and engineers outside the control-room team, over email or

Teams. Markdown source renders poorly in those clients; a print-quality

PDF with title page, TOC, and the existing formatting conventions

(amber executive-summary callout, etc.) is what they actually forward.

Multiple reports in this branch already commit the paired `.md` + `.pdf`

artefacts (see DANGLE, S3-Gap, tthd, hs-HLS).



**How to apply**: once the `.md` is written and the user has signalled

satisfaction with it, ask whether they'd also like the PDF (or just

offer to produce it). Don't wait for them to remember to ask. Build

command:



```bash

cd pdf-tools

uv sync                             # one-time

uv run python md2pdf.py ../foo.md ../foo.pdf

```



Use the same filename stem as the source `.md` so the artefact pair

lands together at the branch root. Wrapper produces a ~15-page,

~110 KB PDF for a ~30 KB Markdown report.



## Test data for development



Files in `/SNS/` are accessed via sshfs mounts with cache. See the parent project's