Roles and skills — guided forms, guide mode, Engineering skill, conversation log, SOPs¶

Part of roles-and-skills. Guided forms, guide mode, what else would help an employee, the Engineering skill, keeping conversations, the SOPs created and changed, and the SOP backlog. Text moved verbatim from roles-and-skills; references such as "above", "below" and "earlier" point into that note or its sibling files.

Guided forms: the assistant collects every field, one question at a time¶

Angel, 2026-09-12: "if the admin asks 'onboard person', the chat can ask all the fields necessary to do it. Same with creating a part number… the assistant must fill all the fields."

The change¶

Today a request is one sentence → one card. That works for an invoice, where three facts are enough. It does not work for a part, which needs a dozen, or for onboarding. So every action gets a declared form: the list of fields, which are required, their types, and how each is resolved (free text, a choice from a list, a lookup in the ERP, or computed). The assistant's job becomes: take what the sentence already gave, ask for the next missing required field, one question per turn, then show the card. The person can answer several at once; the server keeps the partial draft under an id for up to thirty minutes, and the page shows 3 of 7 fields so nobody feels lost.

What stays the same¶

The four reply shapes. A question is still one question; the card still shows what the server resolved; nothing happens before Confirm; a field the person never supplied is asked for, never guessed. "Required" comes from the SOP for that job — the part form is SOP-002's field list, the onboarding form is SOP-009's — so the assistant cannot demand less than the procedure does.

Forms on day one¶

Form	Fields (required in bold)	Runs
Invoice	customer, lines (part, qty), customer reference	today's Sales action
Part	name, description, category, manufacturer + MPN, datasheet link or file, symbol, footprint, reference, value, units, minimum stock, image	the same code as `erp-part`; Engineering skill
Onboard person	email, first, last, departments, NAS	`onboard add --yes`, Administration only
Offboard person	email, confirmation of the name	`onboard remove --yes`, Administration only

Choices are offered, not typed: category from the tree, departments from the registry, customer from a lookup. Where a value can be found it is found — give a manufacturer part number and the distributor lookup fills description, manufacturer and datasheet, then asks only for what is left.

Guardrails specific to forms¶

A draft is bound to the person who started it; another session cannot resume it.
Free-text fields are length-capped and shown verbatim on the card marked as typed.
The description field is checked against the SOP-002 rules (under 100 characters, not the name).
Duplicate check before the card: a part with the same MPN or name, a person with the same email.
Abandoned drafts expire and are logged as such, which is itself a useful signal for the weekly review.

Order¶

Onboarding first — it is admin-only, the fields are few, and it proves the multi-turn draft mechanism end to end. Then the part form, when the Engineering skill is built. The invoice form gains the customer-reference question last, since it already works.

Guide mode: "how do I…" answered from the SOPs, scoped by role¶

Angel, 2026-09-12: "how I create a part number → 'I can do it, but if you want, follow SOP-001'."

The shape¶

A fourth allowed reply shape, guide, beside action, question and none. It is a card, not prose:

How to: create a part number
SOP-001 Part Numbering · owner Engineering · version 1.2      [Open SOP]
One sentence from the SOP's Purpose.
Related: SOP-002 Part Creation
I can do this for you: no — Engineering has no assistant skill yet.   (or: yes — say "create a part …")

Everything on the card is looked up, not generated. The model's only job is to pick which SOP the question is about; the number, title, owner, version, purpose sentence and related list come from an index the site build already has all the facts for.

How it stays inside the walls¶

The index is built at deploy time from the SOP front matter: number, title, owner, version, purpose sentence, which departments may see it (from departments.yml), and which skill, if any, performs it. sop-deploy writes sops.json; the assistant reads that file, never the live pages.
Scoped by role. A Sales person asking "how do I run a build" gets "that is SOP-006 Assembly Builds, which Production owns; ask them" — the name and owner, not the steps. A department sees the full card only for SOPs on its own list. Same rule as the site, enforced in the same registry.
Steps are never paraphrased. The card links to the controlled copy. An assistant that retells a procedure from memory is an uncontrolled copy of it, which is exactly what document control forbids.
"I can do this for you" is computed, from the person's departments and the skills that exist, never claimed by the model.
Off-topic stays off-topic: a question that maps to no SOP gets the standard line, so guide mode does not become a back door to chat.

Build order¶

sops.json from the build (half a day; also gives the SOP site a searchable index for free).
The guide shape in agent.py and the card on the page (a day).
Red-team cases: a Sales person asking for an Engineering procedure gets the referral card, never the steps; a nonsense "how do I" gets the standard line; the card's version matches the file.

What else would help an employee, ranked by how often it would be used¶

"Where is it?" — where is EE-C-0042 → stock location, quantity, batch. Read-only, every department, the single most common question in a shop.
"What am I waiting on?" — open purchase orders and their target dates for Purchasing; builds in production and their state for Production; unshipped orders for Sales. One question, one card.
Print from the chat — print labels for the parts on PO-0004, print the traveler for BO-0007. The templates exist; this is a button on a card, and it must go through the same confirm step because a printer is a real-world side effect.
"Who do I ask?" — every SOP has an owner; every card names one. Cheap, and it stops the question landing on Angel by default.
"What changed?" — what changed in receiving → the last two revision rows of SOP-005 with dates. Reads the same index; keeps people on the current version without re-reading everything.
My onboarding checklist — a new person asks what do I need to set up and gets SOP-009's checklist filtered to their department, with the items already done ticked from the access lists.
Handoff — send this to Angel attaches the whole exchange to an email to Administration. The plan already lists it; it becomes more valuable the moment guide mode exists.
"That was wrong" — a thumbs-down on any card writes a row to the log flagged for the weekly review. This is how the learning loop gets its raw material without anyone filing a report.
Spanish throughout, including the cards, since the SOP titles and purposes are English today; the card can carry a Spanish line if the SOP front matter gains one.

Not on the list on purpose: general questions ("how does reflow work"). The assistant answers from the shop's own documents or not at all; an employee wanting a textbook has the web.

The Engineering skill: a part from a link or a datasheet¶

Angel, 2026-09-12: "if I want to create a new part number and I throw you the datasheet or a link…"

This is the second skill to build, after the first assembly is in. It follows the same shape as Sales: the assistant resolves, the server validates, a card shows the result, a person confirms, and the part is created by the same code erp-part uses today, with the KiCad fields and the next number in the scheme.

Prefer the number to the document¶

Most of the time the datasheet is not needed. A manufacturer part number or a distributor link is enough: the server asks Digi-Key or Mouser through the existing lookup, within the daily budget, and gets back structured facts — description, manufacturer, package, datasheet address, lifecycle status. No PDF is read, nothing is guessed, and the card is filled from the distributor's record. That is cheaper, faster and far harder to fool than reading a document. So the order of preference:

Part number or distributor link → lookup → card. The datasheet is attached as a link.
Datasheet PDF, uploaded → used only for what the lookup could not find (an LCSC-only part, an obscure manufacturer). Text is extracted on the server; the model sees a few hundred words around the title and ordering-information table, not the whole document; it proposes name, description and manufacturer part number for the card. After confirm, the PDF is attached to the new part in the ERP.
Description alone → the assistant asks for a number or a document rather than inventing one.

Rules specific to files and links¶

A file is data, never an instruction. Datasheets are exactly the kind of text that could carry a planted instruction; nothing in a file can trigger an action, only the person's own words can.
Only PDFs, capped at 10 MB, type-checked on the server, never opened by anything but a text extractor, never executed. Stored only as an ERP attachment, only after confirm.
Links are fetched by the server, not the model, restricted to manufacturer and distributor hosts we list, with a timeout and a size cap. Anything else is refused with the reason.
What the card shows: the proposed part number, name, description under the length rule, category, manufacturer and manufacturer part number, the datasheet link, and the KiCad symbol and footprint if a category default exists. Anything the assistant could not establish is shown blank, not filled in.
Duplicates: before the card is offered, the server searches the ERP by manufacturer part number and by name; a match means the card says "this exists as EE-C-0042" instead of proposing a second number.

Why not now¶

The Engineering department has no assistant skill yet and the shop has no real assembly in the ERP. Building this before the first board is loaded means designing against imagination. It goes in right after that, and it reuses erp-part and part-lookup rather than adding a third path to a part.

Keeping the conversations, and learning from them¶

Angel, 2026-09-12: "can we keep a history of what they are prompting? Maybe we can use this history eventually to learn." Yes, and it is the most valuable by-product of the whole thing — but only if what "learn" means is decided deliberately.

What gets written down¶

One row per turn, in a small database on the server, backed up with everything else:

Field	Why it earns its place
when, who, department, channel	answers "who authorised this invoice" a year later
what they typed, verbatim	the raw material; a paraphrase is useless for improving anything
what the assistant proposed, as resolved parameters	shows what would have happened, not what it said
confirmed, corrected, or abandoned	the single most useful signal in the whole table
the result, or the error	separates "we cannot do that" from "we did it wrong"
model, tokens, cost	the budget question, answerable per department

Secrets never land in it: the same never-paste list that governs the chat also governs the log, with pattern redaction for keys and card numbers as a backstop rather than a promise.

Four uses, in order of how soon they pay¶

1. Fixing what is broken. A weekly pass over everything that was corrected before sending, refused, or errored. Each one resolves to a change in a skill, a change in an SOP, or a decision that the assistant should not attempt it. This is where reliability actually comes from.

2. Finding the missing skills. Everything asked that the assistant could not do, counted and ranked. That list is the build queue, written by the people doing the work rather than guessed at here. It also answers whether a department needs a skill nobody thought of.

3. Turning good runs into tests. Every confirmed-correct interaction becomes a fixture in the regression suite: this sentence, with this data, must still produce this order. The suite grows from real work rather than imagination, and a change that breaks last month's behaviour fails before it reaches anyone.

4. Answering whether it works. The counts asked for earlier — drafts raised, corrections before sending, time from sentence to sent invoice — come straight out of this table, per department.

What learning does not mean here¶

It does not mean the assistant quietly adapts. Every improvement lands as a reviewed change to a skill or an SOP, versioned like everything else, so a behaviour change can be read, dated and undone. An assistant that silently learns from its own history will also learn the mistakes nobody caught, and there is no way to tell when it did.

Training a model on this data is a separate decision for much later, and a poor one at this volume. Two people generate hundreds of examples, not the tens of thousands that would justify it — and the same benefit comes free from feeding a handful of real examples into the skill.

Who can read it¶

A person sees their own history. Administration sees all of it. The assistant itself gets no access to anyone else's conversations, because a chat log is exactly the sort of text that would carry an instruction it should never obey. Retention twelve months for the full text, then keep the counts and drop the words; state it in SOP-010 Assistant Use so nobody discovers it later, and put the table in the nightly backup, since it is the record of who authorised what.

The SOPs this creates, and the ones it changes¶

New¶

SOP-010 Assistant Use. The one document every department reads before they are allowed to type at it. What it may do, what it will never do, that the confirmation screen is the thing you are approving and not the sentence you typed, how to correct an invoice raised in error, when to hand the thread to Administration, and the never-paste list. Written when the first skill goes live, not before — earlier and it would describe something imaginary.

SOP-011 Access Review. A quarterly walk of onboard list against who actually works here: every address on every gate, every ERP user and group, every NAS login, every API token and when it was last rotated. Fifteen minutes, and it is the control that catches the account nobody removed. Worth writing now even at two people, because the habit is what survives growth.

Changed¶

SOP-000 Document Control grows to cover skills as well as SOPs. They are procedures with a machine as the audience, so they get the same version, status, owner and revision history — plus one extra gate that SOPs do not have: a skill cannot move from draft to active until its red-team cases pass. Extending the existing document rather than writing a parallel one, because one procedure has one home.

SOP-007 Sales Orders and Invoicing gains the assistant as a second path to the same result, with the interface as the fallback, and the rule that a corrected invoice is corrected the same way whichever path created it.

SOP-009 Personnel Onboarding gains the department flags, the fact that a person can hold more than one, and assistant access as a step that is granted with the department rather than separately.

The SOP backlog, with triggers¶

The set covers what the shop does today. These are the gaps, each with the event that should make us write it. Writing them before the trigger produces documents nobody has tested.

Document	Trigger
Engineering Change Control	the first board revision that changes a BOM after stock exists
Returns and Repairs	the first customer return
Stocktake and Cycle Counting	the first time the count on the shelf disagrees with the ERP and it matters
Test and Serialisation	the first product shipped with serial numbers and recorded results
Disaster Recovery	before the next hardware change; the tooling and a proven restore already exist, the written procedure does not
Supplier Approval	the first supplier chosen for something other than price and availability
Firmware Release	the first firmware shipped to a customer as an update
Quoting	when quotes stop being occasional; today they live inside Sales Orders and Invoicing

Two of these deserve promoting early regardless of the trigger. Disaster Recovery because the restore has been proven but never written down, and the person who needs it may not be the person who built it. Engineering Change Control because revisions are already in the part-number scheme with no procedure attached, and the failure mode is building the wrong revision, which costs a batch.