SuperAPI AI Directory

understand_processflow_rules_and_gimmicks

General & other

View repository

Updated 10-16 04:53

About this skill

ProcessFlow — Rules & Gimmicks (consolidated)

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-overview are 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):

  1. Load skills: this one + processflow-review + processflow-app; read engagement memory.
  2. Start helper app (python3 app.py), connect Chrome MCP, token from localStorage, ingest company (always use the project_id filter), load transcript(s) into the app.
  3. 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):

  1. Review all of the company's processes (list + scores + short description). Know that: source_image_url set = real workshop canvas (photo), null = AI-synthesized (entire canvas is an assumption → especially suspicious of duplicates/hallucinations).
  2. 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).
  3. 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.
  4. 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).
  5. 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>-OS for 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 from report.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 from next_steps or 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_report sometimes 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 via process_solutions.created_at .
  • Solution class dialog ("Individual software"/"Workflow") writes type unreliably — on save, "tool" has already ended up there. In the DB, the solutions.typeenum only tool | 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 (especially external_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.rationales and phases the 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: phases before 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_approach new, 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_system is 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_priority is 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 fill persists onto the spinbutton uid + then Tab (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_screenshot in Page.captureScreenshot timed out runs, measure the rendering via DOM (find SVG text nodes, compare getBoundingClientRect of 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:

  1. Approvals: solution_concept_reviewed_at/_by set (by a human!).
  2. Hours triad: phases sum = estimated_hours = next_steps sum.
  3. Executive Summary present (> ~100 characters) — full reworks leave it empty.
  4. 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.
  5. Diagrams: 2 each (flow+architecture), rendering visually checked.
  6. Solution links = concept status (auto-link trap!), existing flags correct, either-or only linked once, shared <firma>-OSsolution everywhere.
  7. Priority view 1…N = audited set (spinner, see §7).
  8. 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:

  1. Header: Review completed, N processes audited + approved, note "the priority view in ProcessFlow is the authoritative view", status date.
  2. Recommendation in one sentence (box).
  3. 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.
  4. "+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.)
  5. 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).
  6. 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.
  7. Questions for the next customer appointment (ERP version/API, license status, interfaces, open names).
  8. 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.