Knowledge skill from the real engagements (ZIWA → Stütz → Bettenrid). Supplements
processflow-review (guardrails/error patterns) and processflow-app (driver) — does not replace them.
In case of conflict: latest user instruction > this skill > default.
⚠️ CURRENT SCOPE RULE (Martin, 07/2026): From now on, only 5 processes per company will be worked in depth (no longer 10). Older "top 10/max 10" statements in
processflow-review/processflow-overvieware thereby overridden — triage stays the same, the cut is at 5. Push unworked, unaudited AI drafts via the priority spinner BEHIND the audited ones.
1 · Standard procedure for a new company (binding order)
Phase A — Kickoff (session start):
- Load skills: this one +
processflow-review+processflow-app; read engagement memory. - Start helper app (
python3 app.py), connect Chrome MCP, token fromlocalStorage, ingest company (always use theproject_idfilter), load transcript(s) into the app. - Read the transcript COMPLETELY: industry/products exactly, real systems/ERP, who said what, customer priorities. Note ASR mishearings (when in doubt, check names against canvas photos).
Phase B — Duplicate/redundancy pass over ALL processes (before any individual work):
- Review all of the company's processes (list + scores + short description). Know that:
source_image_urlset = real workshop canvas (photo), null = AI-synthesized (entire canvas is an assumption → especially suspicious of duplicates/hallucinations). - Assign each process its scenario from the transcript — don't trust the name (Bettenrid: "Kundendubletten – Falschbuchungen" = accounting OP reconciliation, NOT the CRM data topic; several email/appointment drafts meant the same process).
- Merge proposal as an artifact/overview to the human (never merge silently):
per cluster one main process (the one with a canvas photo or the clearest transcript evidence)
- list of duplicates/satellites it absorbs; name suggestion for the main process if the AI name poorly matches the scenario; reasoning per decision.
- Implement after human approval:
- Duplicates → enable “Nicht benötigt” (Not needed) on the solution-concept tab (the native toggle next to “Berater-freigegeben,” meaning Consultant-approved; DB column
processes.solution_concept_not_needed— REST-readable for verification). Do not delete — they remain traceable. - Rename main processes (approved proposal): the process name is a real text field in the canvas metadata → directly editable (no Copilot needed).
- Document merge decisions in the team feed and
list_notes(which process absorbs which).
- Duplicates → enable “Nicht benötigt” (Not needed) on the solution-concept tab (the native toggle next to “Berater-freigegeben,” meaning Consultant-approved; DB column
- Top-5 selection (current scope rule, see above): analysis order + customer priorities from the transcript; reclassifications with ▲/▼ + justification; set priority spinner 1…5, rest behind it.
Phase C — Individual work, 1 by 1 (per process §§2–8): research → critique → Copilot rework → Steps → Solutions → diagrams → phase field → verify live. Artifact checkpoints between the stages: (a) transcript analysis, (b) solution planning with researched prices — human approves each direction, ONLY THEN write into ProcessFlow.
Phase D — Completion: Final sweep (§9) → Dominik HTML 4+1 (§10). Approvals are set by the human.
Writing order per process: concept text → Executive Summary (own field, drifts!) → implementation steps → Solutions/Tools → diagrams → phase field → guards. After EVERY step verify live (DB grep or screenshot), never trust the chat response.
2 · Style rules solution concept + Executive Summary (Martin, binding)
- NO data protection/GDPR in the solution concept or the Executive Summary. No "## Data protection" sections, no EU hosting/DPA/third-country notes, no tool exclusion lists ("ChatGPT excluded", "per tool exclusion list"). Real legal points to clarify (e.g. consent situation) write as a normal analysis step in Phase 0.
- NO canvas/photo references ("per canvas photo", "not captured in the canvas").
- NO estimate/verification hedges ("estimate — to be confirmed", "check in advance", "not confirmed"). Points to clarify belong as an analysis step in the phases (e.g. "check license situation" = part of Phase 0), never as a disclaimer in the initial situation.
- NO frequency/effort indications in the initial situation (they are in the canvas).
- NO meta disclaimers ("no AI use", "classic threshold logic").
- No A/B variants when the customer has decided (Bettenrid P7: management wanted forecasting → only the OS solution, Power BI completely out — do not keep as an "entry point").
- No tool hardcoding for single-source research: If the research finds only ONE provider
and price/integration are open → Evaluation-first: Phase 0 evaluates the market candidate
("e.g. adelo") + further providers + ALWAYS a
<firma>-OSself-build variant (especially when the customer wants "few systems"). Decision criteria into the concept; diagram nodes neutral ("scheduling solution, selection in Phase 0"); steps "Configure selected solution". - Link one shared OS solution
<firma>-OSfor ALL OS processes — not a separate one per module ("the software becomes the OS"). Tool recommendation is then also named accordingly. - Never link either-or twice: only the primary recommendation as a Solution; alternatives and fallbacks remain in the text (otherwise costs add up: Omnifact+Langdock = €45/m error).
- Real system names everywhere (Navision, not "business management system (ERP)") — as soon as the name is verified (Canvas photo beats transcript wording; ASR mishears names: Vision→Navision, Petra Tagessa→Pedram Taghizadeh, Samuel Thomas→Thomas Sengl).
- Customer-side, confident tone; mirror the structure/house style of good processes
(
## Ausgangslage→ Phases →### Empfehlung); roles instead of people's initials.
3 · The Phase Field (IMPLEMENTATION STEPS / "~Xh implementation")
- The "~Xh implementation" header and the visible "IMPLEMENTATION STEPS (Σ Xh)" block read from
report.phases— NOT fromreport.next_steps(that is what the concept copilot writes). Both drift apart → always keep synchronized: phases sum = estimated_hours = next_steps. - The copilot CANNOT write to
phases— (it says so itself). More reliable native way: Fill rows in the IMPLEMENTATION STEPS editor via MCP (textarea/input value-setter is enough for the state) → then click the “Speichern” (Save) button at the top of the solution-concept editor — that also commits the phases. Auto-save alone does NOT fire on automated inputs. - Editor controls: “Schritt hinzufügen” (Add step) creates rows; delete uses the
lucide-xicon per row (no trash icon); phase headings = rows with 0h. First count how many old rows exist — otherwise new ones stack on top of old (22 rows/98h trap). - “Schritte vorschlagen” (Suggest steps) pulls from
implementation_custom— not fromnext_stepsor the tool variant. With "no development project recommended" (tool cases) exactly one 0h row appears → the button is useless there; transfer steps manually from the next_steps (Bettenrid P4).
4 · Save/persistence gimmicks (the most expensive traps)
- NEVER click “Neu generieren” (Regenerate) — it overwrites all audit fixes in the concept.
- After every copilot run: reload the page + cross-check the DB (before/after grep). The copilot sometimes claims completion without a tool call; runs hang (>2 min = probably not saved); React state shows values that were never persisted.
update_reportsometimes automatically links external components as solutions ("+N external building blocks linked") → after every report update, cross-check the solution links and remove anything foreign (that is how Easy Contract ended up on the customer service process). Clarify causation viaprocess_solutions.created_at.- Solution class dialog ("Individual software"/"Workflow") writes
typeunreliably — on save, "tool" has already ended up there. In the DB, thesolutions.typeenum onlytool|custom_workflow; OS/individual web apps =custom_workflow(the UI badge shows "Individual software" for that depending on the view — the badge counts, not the raw column). The copilot hallucinates fields (kind,is_individual_software) — never believe it, check via REST?select=type. - Existing/New toggles (Radix switches): unreliable to read after clicking → only count as confirmed after a reload; clicks require the full pointer event sequence.
- Copilot sometimes writes literal
\nescapes into text fields (especiallyexternal_components) — the UI then shows a visible "\n-" text instead of line breaks. After field rewrites, grep the field for the two characters backslash+n; fix via micro-prompt ("replace every literal \n- with a real line break") or re-dictate the field entirely with a clean list. - Non-Copilot fields:
gdpr_compliance(E),process_scores.rationalesandphasesthe Copilot cannot write — stale references (winkk/n8n/Mistral/old variants) survive there. Before presenting, pull the PDF export and check whether these fields are output. - Token ~1 h: empty REST responses/
PGRST303/KeyError: 0= token expired → pull a fresh token from Chrome-localStorage, do NOT doubt the data. Local helper-app JSON is a snapshot — always read the numbers live for the deliverable. - Direct REST writes only with explicit user OK per case (guardrail: in-app AI + native
controls). Exception precedent:
phasesbefore the save-button route was known.
5 · Operating the in-app AI (Concept Copilot) correctly
- Work mode (not Ask). Canvas changes generate suggestions → "Apply" required. Note: the mode resets to Ask after a browser/Chrome restart — check it on the page before every prompt, otherwise it only responds descriptively ("As soon as you switch to Work…").
- Micro-prompts instead of bulk prompts: large chained requests end in endless reasoning loops (>2 min "Reasoning…") — one targeted change per message; on a hang, reload the page and send again. For targeted text corrections, specify exact replacements ("Replace X with Y"), don't describe them.
- Work in a formatting-preserving way ("no full rewrite") — unless a field is intentionally meant to be new.
- The Executive Summary is a separate field and is NOT carried along on concept updates —
always check/update it separately. A full rework via Copilot can even leave it EMPTY
(Bettenrid P1/P2:
concrete_approachnew,executive_summary= empty, only noticed in review) → after every rework, check for non-emptiness. update_reportwrite fields (disclosed by the Copilot itself — whatever is missing can only be done natively or not at all):ai_content_score,ai_percentage,ai_solution_categories,ai_technologies,concrete_approach,estimated_hours,executive_summary,external_components(_structured),implementation_custom/_recommendation/_tool_based,known_solutions,next_steps,pain_point_categories,quick_win_or_project,score_reasoning,solution_level(_reasoning),tool_recommendations.- The Copilot solution search often fails to find existing entries ("Solutions searched · 0 found" despite an existing catalog entry) → it then creates duplicates or falsely claims an entry "was not assigned to this process". For EXISTING entries always use the native "Assign manually" picker; use the Copilot only to remove assignments and to create project-specific solutions (OS modules).
6 · Solutions map & catalog
- Existing/New is a property of the LINK, rather than the catalog entry:
process_solutions.is_existing_systemis per process assignment — the same catalog entry can be Existing on process A and New on B. - “Solution bearbeiten” (Edit Solution) on a process edits the CATALOG ENTRY — a rename propagates to ALL links. Usable as a bulk fix ("ERP system (not further specified)"→"Navision" fixed 25 links at once), but dangerous with shared entries: count beforehand whether links exist outside the project.
- Catalog entries are org-scope and appear in the pickers of ALL customer projects → name customer-specific systems uniquely; in the process picker never click "…create as tool" if the entry could exist (that is how the map duplicates arise).
- Bulk hygiene native: Project settings → Tools: "Tausch (Swap)" replaces a tool in all N processes of the project (existing marks + notes are preserved; the target entry must exist — the dialog cannot create one) · "Duplikate zusammenführen (KI) (Merge duplicates with AI)" for name duplicates (e.g. "Microsoft Outlook" vs. "… / Exchange Online").
- The initial analysis sprays default tools across dozens of processes (Bettenrid: winkk.ai×40, Mistral×50, Easy Contract×28 of 68) → plan map hygiene as a fixed item; the "N processes" column of the tools page is the indicator. Concept fixes do NOT propagate the links — after every concept change, cross-check "Assigned Solutions" (concept↔links drift).
7 · Order, roles & approvals
processes.manual_priorityis THE analysis order — the authoritative view for all stakeholders ("the priority view is correct") and the number range in handovers/deliverables.- Set spinner (working method, 07/2026): On the project process list , each row has a “Manuelle Priorität” (Manual priority) spinbutton. With the appropriate organization/project role, MCP
fillpersists onto the spinbutton uid + thenTab(real/trusted CDP events). JS value setters and synthetic events do NOT save (the UI shows the new value, the DB keeps the old one — always verify via REST?select=manual_priority). Consultant login without access → delegate with exact target numbers. - After the audit round, restore the priority view: audited processes to 1…N, displaced unaudited drafts to N+1/N+2 — otherwise the "correct" view shows wrong entries.
- Never invent your own number ranges: Artifacts/handovers reference
manual_priority; old numbers at most as an alias alongside (Bettenrid lesson: artifact P# vs. priority field = two truths, confusion in the team). - “Berater-freigegeben” (Consultant-approved) toggle =
processes.solution_concept_reviewed_at/_by— REST-readable for status boards; the "Consultant OK" badge in lists reads from it. - Multiple actors on the same project: pull a live delta before every work/re-audit run
(
solutions?updated_at=gte.<datum>,process_solutions-Links, report marker grep) instead of trusting the local helper snapshot. Document and coordinate external edits — never silently revert them (maybe the other person knows something new).
8 · Diagrams
- Per process End-to-end flow + architecture (Dominik's G1); exception: trivial single-tool cases.
- Short labels with an explicit
<br/>line break (2–3 lines of ~25 characters each) — the renderer cuts off long single-line labels at the box width. Give the copilot the Mermaid code EXACTLY specified ("take over unchanged"), otherwise it builds long labels/subgraphs/person names. flowchart TD, ≤ ~10 nodes architecture, no subgraphs in the flow, real system names, captions on the customer side (never "pink/:::custom/C4/layer/Mermaid").- After every diagram update, verify visually via screenshot (diagrams subtab) — source text clean ≠ rendering clean. Color logic: magenta=custom software, green=new tool, black=existing, gray=actor.
- Edge labels also get cut off — keep them short ("Golden Records", not "Cleaned records · Golden Records · …").
- Screenshot timeout fallback: If
take_screenshotinPage.captureScreenshot timed outruns, measure the rendering via DOM (find SVG text nodes, comparegetBoundingClientRectof text vs. box) — don't blindly continue. - Browser lock: "The browser is already running for …chrome-profile" = ANOTHER session (colleague/second terminal) holds the MCP Chrome → ask the user to release it; do not start --isolated (your own session would have no login).
9 · Final sweep before handover (checklist, all live from the DB)
Before "done", run ONE batch sweep over all processed processes — never check them off one by one:
- Approvals:
solution_concept_reviewed_at/_byset (by a human!). - Hours triad: phases sum =
estimated_hours= next_steps sum. - Executive Summary present (> ~100 characters) — full reworks leave it empty.
- Style grep across ALL text fields, not just the most recently edited:
concrete_approach,executive_summary,external_components,solution_level_reasoning,tool_recommendations,known_solutions,implementation_recommendation. Prohibited list: "## Datenschutz"/"### Datenschutz", "Canvas-Foto"/"lt. Canvas", "Schätzung —", "zu bestätigen", "nicht bestätigt", "zu verifizieren", literal backslash-n. Legacy issues hide in the BODIES of concepts from earlier editors — sweeps that only check ExecSums miss them. - Diagrams: 2 each (flow+architecture), rendering visually checked.
- Solution links = concept status (auto-link trap!), existing flags correct,
either-or only linked once, shared
<firma>-OSsolution everywhere. - Priority view 1…N = audited set (spinner, see §7).
- Clarify external flags: take colleagues' AI reports seriously, trace causation via
created_atDocument timestamps (don't guess who it was), answer in the team feed.
10 · Ideal end result: the Dominik HTML (4+1) — standard finish
The final deliverable that has proven itself ("went down extremely well"): a single self-contained HTML file (inline CSS, system fonts, no external dependencies, light, shareable via Slack — NOT a claude.ai artifact), stored in the company folder. Content in this order:
- Header: Review completed, N processes audited + approved, note "the priority view in ProcessFlow is the authoritative view", status date.
- Recommendation in one sentence (box).
- The top 4 as cards in presentation dramaturgy: 2 quick wins first (trust,
small hour counts), then the strategic
<firma>-OSmodules as ONE platform story. Per card: chip (quick win/strategic + hours), department, solution, 1–2 verbatim transcript quotes (strongest element!), 2–3 sentences why. - "+1" outlook: the decision-maker's explicit wish (GF priority 1) as a fifth slide that tells the OS story to its end and ends with the decision-maker — incl. documented swap option in case Dominik wants the other dramaturgy. (Observe the 4-to-present gate: 2+2 balance, different departments, every top customer priority covered or justified, max. 1 own product.)
- Presentation tips: open with customer quotes; OS as one story; name quick-win hours first; use appointment anchors (e.g. anniversary); do NOT improvise "on request" prices; confidently refer open technical questions to the clarification appointment; feed the impact assessment back to the customer (5th pillar).
- Table of all audited processes in priority order with ProcessFlow deeplinks
(
…/process/<id>/wizard?tab=feasibility), hours, type chips; grand total; note on postponed unaudited drafts. - Questions for the next customer appointment (ERP version/API, license status, interfaces, open names).
- Footer: basis (transcripts, canvas photos, tool research with date), "HI approval & presentation appointment with Dominik". Before sending, open the file in the browser and check it via screenshot.
11 · Never (hard)
- Set HI/consultant approval → always the human. Name presentation appointment → Dominik.
- Commit customer data (
data/). Click "regenerate". Believe the copilot's chat response without a DB check. Hard-wire the tool for single-vendor research.
References
Guardrails/error pattern register: processflow-review · Driver/Chrome MCP: processflow-app ·
Workflow: processflow-overview → processflow-run <prozess>. Canonical standard: Dominik's SOP.