--- name: risk3y-user-guide description: Expert user knowledge for Risk3y. Use when a user needs help navigating the app, understanding features, managing risks, controls, reviews, registers, sharing, billing, matrix configuration, MCP setup, or team permissions. Includes HSE NZ/AU Skills companion collection. user-invocable: true --- # Risk3y User Guide This Skill covers everything a Risk3y user needs to know to get value from the product — from signing up to managing a mature, well-shared risk register. Use this Skill when you need to: - Understand how Risk3y is structured and what each part does - Get started quickly as a new user or team - Manage risks, controls, and reviews confidently - Configure your risk matrix to match your organisation's methodology - Share risk registers with team members or external stakeholders - Set up BYO-AI access through MCP - Understand your plan, limits, and how to upgrade _Last updated: 2026-06-28_ --- ## What is Risk3y? Risk3y is a clean, focused, cloud-based risk register application. It is built for safety teams, compliance managers, operations teams, and consultants who need a structured, shareable risk register without the complexity of a full HSE platform. ### The core problem Risk3y solves Most organisations already have an HSE system, but their risk registers are often: - Hard to share with the right people - Buried inside larger systems nobody uses day-to-day - Maintained in spreadsheets that are flexible but fragile Risk3y gives you a structured register, multi-user access, role-based permissions, and easy sharing — plus optional BYO-AI access through MCP. ### Key concepts | Concept | What it means | | --------------- | ------------------------------------------------------------------------------------------------------- | | **Tenant** | Your organisation in Risk3y. All your data is isolated to your tenant. | | **Register** | A scoped collection of risks. A tenant can have multiple registers (e.g. Site A, Project X, Corporate). | | **Risk** | A recorded potential harm — with a description, score, controls, and review history. | | **Control** | A measure in place to prevent or reduce a risk. | | **Review** | A recorded check on whether a risk and its controls remain current and effective. | | **Risk Matrix** | Your organisation's configured likelihood × consequence scoring grid. | | **MCP** | A protocol that lets your own AI tool read or write your risk register safely. | --- ## Geographic availability Risk3y is currently available in **New Zealand and Australia only**. Users from other countries can register their interest via the waitlist. --- ## Getting started ### Signing up and creating your organisation 1. Sign up at the Risk3y website. 2. Select your country (NZ or AU). 3. Enter your organisation name — this becomes your tenant. 4. Name your first risk register. 5. Choose a starter risk matrix: - **5×5 Standard** (recommended) — 5 likelihood levels × 5 consequence levels, 4 risk bands - **3×3 Simple** — 3 likelihood levels × 3 consequence levels, 3 risk bands - **Skip / set up later** — configure in Settings → Matrix after onboarding 6. You land on the "All set!" screen showing your next three actions: add a risk, invite your team, and discover MCP. The person who creates the organisation automatically becomes the **Tenant Owner**. ### Getting Started checklist After onboarding, your dashboard shows a collapsible "Getting Started" card tracking progress through key milestones: - Create your first risk register _(auto-checked)_ - Set up your risk matrix _(auto-checked if preset chosen)_ - Add your first risk - Invite a team member - Create a shared view - Connect your AI tool via MCP The card is dismissible and re-accessible from the sidebar footer. --- ## Registers ### What is a register? A register is a scoped list of risks. You might have one register per site, project, business unit, or function. Each register is independently configurable and shareable. ### Register modes Each register runs in either **Compact** or **Expanded** view (toggle in the register toolbar). This controls how much detail is shown on screen — not the register's data model. Registers also have a **Simple** or **Advanced** mode that controls which features and fields are available: | Mode | What it includes | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Simple** | Risk title, description, knowledge, consequence, likelihood, controls, reviews | | **Advanced** | Everything in Simple, plus: top event (bow-tie hinge), structured threats, bow-tie control wiring, job role ownership, education methods | **Solo plan tenants are locked to Simple mode.** Team and Team+ plans can use Advanced mode. > Switching a register from Advanced to Simple hides advanced fields (threats, bow-tie links) but does not delete them. Switching back to Advanced restores the data. ### Creating a register - Click "New register" from the dashboard or sidebar. - Name it and optionally write a scope description. - Choose Simple or Advanced mode (Team/Team+ only). --- ## Risks ### What is a risk? A risk is a recorded potential harm — something that could go wrong in your operations. Each risk has: - **Title** — short, clear label - **Description** — what the risk is and why it matters - **Knowledge** — supporting context, evidence, or background (Markdown supported) - **Initial risk score** — consequence × likelihood before controls - **Residual risk score** — consequence × likelihood after controls - **Controls** — measures in place to prevent or reduce the risk - **Reviews** — a history of check-ins on this risk - **Status** — open, closed, archived ### Adding a risk 1. Open a register. 2. Click **Add risk** (or use the empty-state prompt on a new register). 3. Fill in the title, description, and knowledge. 4. Set the initial consequence and likelihood using your configured matrix. 5. Add controls. 6. Set the residual consequence and likelihood. 7. Save. ### Risk scoring Risk3y uses: ``` Risk score = Consequence × Likelihood ``` Your organisation defines what each consequence and likelihood level means. The calculated score maps to a risk level (e.g. Low, Medium, High, Critical) based on your configured bands. **Initial risk** is the score before any controls are applied. **Residual risk** is your judgment of the score given the controls you believe are in place. Risk3y does not automatically calculate residual risk from controls — you set it. ### Risk status | Status | Meaning | | ------------ | ----------------------------------------------------- | | **Open** | Active risk being managed | | **Closed** | Risk no longer applies or has been resolved | | **Archived** | Retained for reference but no longer actively managed | --- ## Controls ### What is a control? A control is a measure your organisation has in place to prevent a risk from occurring or to reduce its impact. Each control has: - **Description** — what the control is - **Control type** — preventive, detective, directive, or corrective - **Owner** — the job role or person responsible - **Verification frequency** — how often this control should be checked - **Last verified** — when it was last confirmed to be operating ### Control types | Type | Purpose | Bow-tie position (Advanced mode) | | ---------- | ----------------------------------------- | -------------------------------- | | Preventive | Stops the risk from happening | Prevention (left side) | | Detective | Detects conditions before the event | Prevention (left side) | | Directive | Instructs people how to avoid the event | Prevention (left side) | | Corrective | Reduces harm after the event has occurred | Mitigation (right side) | ### Adding a control 1. Open a risk. 2. Click **Add control**. 3. Enter the description and select the control type. 4. Assign an owner and set the verification frequency. 5. In Advanced mode, you can optionally link the control to a specific threat. --- ## Advanced mode: Threats and Bow-Tie _Available on Team and Team+ plans with Advanced register mode._ ### What is the bow-tie model? The bow-tie model is a structured way to understand a risk. It maps: - **Threats (left side)** — causes that lead to the central harmful event - **Top Event (centre)** — the single key moment where harm occurs - **Controls** — prevention controls on the left, mitigation controls on the right ### Top Event The top event is the bow-tie hinge — the event that, if it occurs, causes the harm described in the risk. Each risk in Advanced mode can have one top event. Examples: | Risk title | Top event | | ------------------------- | ----------------------------------------- | | Worker falls from height | Person loses contact with working surface | | Vehicle collision on site | Vehicle strikes person or structure | ### Threats Threats are the causes that lead to the top event. A risk can have multiple threats. Each threat has: - **Description** — what the threat is - **Threat type** — human, equipment, environment, organisational, or third-party - **Proximity** — immediate (direct cause) or underlying (systemic factor) Prevention controls can be linked to specific threats to show exactly which threat each control addresses. --- ## Reviews ### What is a review? A review is a recorded check on whether a risk and its controls remain current and effective. Reviews create an audit trail showing your register is actively maintained. ### Recording a review 1. Open a risk. 2. Click **Record review**. 3. Select an outcome (e.g. no change, action required, score updated). 4. Add notes and any evidence. 5. Assign follow-up actions if needed. 6. Save. ### Review scheduling Set a review cadence per risk (e.g. monthly, quarterly, annual). Overdue reviews are surfaced in the register view so nothing slips. --- ## Risk matrix configuration ### What is the risk matrix? The risk matrix is your organisation's scoring grid. Risk3y does not impose a fixed methodology — you define what each likelihood and consequence level means. ### Configuring the matrix Go to **Settings → Matrix**. You can define: **Likelihood levels:** | Field | What to fill in | | ------------- | ---------------------------------------------------- | | Label | Short name (e.g. Rare, Likely) | | Meaning | What this level means in your organisation's context | | Numeric value | Number used in the formula | **Consequence levels:** | Field | What to fill in | | ------------- | ------------------------------- | | Label | Short name (e.g. Minor, Severe) | | Meaning | What this level means | | Numeric value | Number used in the formula | **Risk levels (bands):** | Field | What to fill in | | ----------- | --------------------------------------------- | | Name | e.g. Low, Medium, High, Critical | | Score range | Minimum and maximum score for this band | | Meaning | What this level requires in your organisation | | Colour | Display colour | ### Starter presets If you skipped the matrix during onboarding, you can apply a preset in Settings → Matrix: - **5×5 Standard** — suitable for most organisations - **3×3 Simple** — faster to fill, easier for smaller teams You can also build your own from scratch. --- ## Users and roles ### Inviting team members Go to **Settings → Users** and click **Invite user**. Enter their email address and assign a role. They will receive an invitation email. ### Tenant roles | Role | What they can do | | -------------------- | ------------------------------------------------------------ | | **Tenant Owner** | Full access — owns the tenant, billing, and all settings | | **Tenant Admin** | Manages users, roles, and tenant configuration | | **Billing Admin** | Manages the Stripe subscription and invoices | | **Risk Manager** | Owns risk register configuration and the full risk lifecycle | | **Risk Contributor** | Creates and edits assigned risks and controls | | **Risk Reviewer** | Reviews risks and records review outcomes | | **Read-Only User** | Can read permitted risks and reports | ### What each role can do with risks | Action | Risk Manager | Risk Contributor | Risk Reviewer | Read-Only | | --------------- | ------------ | ---------------- | ------------- | --------- | | View risks | ✅ | ✅ | ✅ | ✅ | | Create risks | ✅ | ✅ | ❌ | ❌ | | Edit risks | ✅ | ✅ | ❌ | ❌ | | Archive risks | ✅ | ❌ | ❌ | ❌ | | Add controls | ✅ | ✅ | ❌ | ❌ | | Record reviews | ✅ | ❌ | ✅ | ❌ | | Manage matrix | ✅ | ❌ | ❌ | ❌ | | Share registers | ✅ | ❌ | ❌ | ❌ | ### Managing multiple organisations If you manage risk registers for multiple clients (e.g. as a consultant), you can create and switch between separate organisations without logging out. - Click **+ New org** in the workspace switcher to create a new organisation. - Select from the switcher to change context — data from other organisations is never visible in the active context. - You become Tenant Owner of each organisation you create. --- ## Sharing ### Sharing types | Type | Purpose | | ------------------------ | -------------------------------------------------------------- | | **Internal team access** | Normal tenant users with assigned roles | | **Team share link** | A curated read-only view for selected internal users or groups | | **Public share link** | A read-only public page for selected risks or register views | ### Creating a public share link Go to **Settings → Share links** or use the share action on a register. You can: - Name and describe the share - Select which risks or views to include - Choose which fields are visible (e.g. show risk name and controls; hide internal notes) - Set an optional expiry date - Set an optional password - Revoke at any time **Fields hidden by default on public shares:** - Internal notes - User email addresses - Billing information - MCP client details - Private evidence - Audit history ### Use cases for public sharing - Share a site risk register with contractors - Share a project-specific risk view with a client - Publish a simplified register view for consultation - Share a summary view for a board or regulator --- ## Export ### Available export formats | Format | What it produces | | -------------------- | -------------------------------------------------------- | | **CSV** | Spreadsheet-compatible data; can be re-imported | | **Markdown** | Clean document suitable for Notion, Confluence, or wikis | | **HTML (printable)** | Card-style layout; open in browser → Print → Save as PDF | Access exports from the register view using the **Export** button or menu. You can filter by status, risk level, or critical risk flag before exporting. --- ## MCP (Bring Your Own AI) ### What is MCP? MCP is a protocol that lets your own AI tool (such as Claude, ChatGPT, or another assistant) connect to your Risk3y register. Risk3y exposes safe, permission-aware access to your data — you choose the AI tool. > Risk3y does not sell AI tokens or host a model. You bring the AI; Risk3y secures the access. ### What your AI can do via MCP **Read (always active):** - Search risks and filter by status, score, or overdue reviews - Get a specific risk with its controls and review history - Get a register summary — counts, top-scored risks, overdue reviews - Generate an analytical report across permitted data **Write (when you grant write access):** - Create and update risks - Add and update controls - Record reviews - Create, update, or delete risk groups - Manage job roles - Manage share links (if scoped) All MCP actions are audited. Write actions your AI suggests can be routed through a proposal-and-approval flow so a human reviews changes before they apply. ### Using MCP to query the HSE prosecutions database Risk3y includes a read-only prosecutions knowledge base covering workplace health and safety enforcement cases from New Zealand, Australia, and the United Kingdom. Your AI tool can query this database through MCP to ground risk analysis in real enforcement patterns. **Why this is useful:** - See which control failures have led to prosecutions in your industry - Identify recurring duty-holder failures that match your operating risks - Use prosecution themes to strengthen your control design and review agenda - Ask your AI: "Are there prosecution cases that match our highest-residual risks?" **Prosecution read tools available to all MCP clients:** | Tool | What it does | | --------------------------- | ------------------------------------------------------------------------------------------------ | | `prosecution_search` | Search the database by keyword, legislation, jurisdiction, industry, or year | | `prosecution_get` | Get full details of a single case including knowledge notes and attached judgment documents | | `prosecution_stats` | Summary counts by year, legislation, and jurisdiction | | `prosecution_field_values` | List distinct values for a field (e.g. all industries in the database) — useful before filtering | | `prosecution_document_read` | Extract the plain text from an attached judgment document (RTF, PDF, HTML) | **Example queries to ask your AI:** - "Search for prosecutions in the construction industry from the last three years." - "Find NZ Health and Safety at Work Act cases involving falls from height." - "Summarise the prosecution that matches ID 142 and tell me what control failures were cited." - "Read the judgment attached to prosecution 98 and extract the key lessons." - "What are the most common failure modes in Australian prosecutions involving contractors?" - "Cross-reference our open high-residual risks against prosecution themes in our industry." **Filtering options for `prosecution_search`:** | Filter | Values | | -------------- | --------------------------------------------------------------------------------------- | | `legislation` | `HSWA` (NZ Health and Safety at Work Act), `HSEA` (older NZ), or an AU legislation name | | `jurisdiction` | `NZ`, `AU`, `UK`, `AU-VIC`, `AU-NSW`, etc. | | `country_code` | `NZ`, `AU`, `GB` | | `year` | Decision year as a number | | `industry` | Partial text match (e.g. `construction`, `agriculture`) | **Important:** Prosecution data is a learning resource, not a source of legal advice. Use case patterns to inform your risk controls and review priorities — always apply your own judgment and seek specialist legal advice for regulatory compliance questions. --- ### Setting up MCP 1. Go to **Settings → MCP Clients**. 2. Click **Create MCP client**. 3. Give it a name that identifies the AI tool (e.g. "Claude Desktop — Scott"). 4. Choose scopes: - Read-only if you want the AI to analyse but not change data - Read-write if you want the AI to propose or apply changes 5. Risk3y shows the connection URL and API key. 6. Copy the connection details into your AI tool's configuration. 7. Test the connection by asking your AI to run `risk_search`. 8. Monitor activity in the **MCP audit log**. ### Security notes - Each MCP client is tenant-scoped — it can only access your organisation's data - Scopes are enforced server-side — the AI cannot exceed the permissions you granted - All read and write actions are logged - You can revoke a client at any time from Settings → MCP Clients --- ## Billing and plans ### Plans | | Solo | Team | Team+ | | ------------------- | -------- | -------- | -------- | | Monthly price (NZD) | $32 | $108 | $272 | | Users included | 1 | 10 | 50 | | Registers included | 1 | 5 | 20 | | Risks per register | 100 | 500 | 2,000 | | MCP access | ✅ | ✅ | ✅ | | Advanced mode | ❌ | ✅ | ✅ | | Support | Standard | Standard | Priority | All plans include a **14-day free trial**. > Solo plan users are locked to Simple register mode. Team and Team+ plans unlock Advanced mode. ### Critical Risk Verification add-on CRV is a separately purchasable add-on (not included in any base plan). It unlocks: - **Verifications** — field check rounds for critical controls - **Worker Consultation** — structured worker engagement on risk controls - **Maturity Assessment** — formal assessment of risk management maturity These three tabs appear with a lock icon when CRV is not active. ### Managing your subscription Go to **Settings → Billing**. From here you can: - View current plan and usage - Upgrade or downgrade your plan - Access the Stripe billing portal for invoices and payment methods ### Entitlement limits Risk3y enforces plan limits server-side. If you reach a limit (e.g. maximum registers or risks), you will see a prompt to upgrade. Overage is not automatically billed — you are asked to upgrade first. --- ## Audit log Risk3y keeps a full audit trail of changes to your risk register. Go to **Settings → Audit log** to review: - Who changed what and when - MCP client activity - User invitation and role changes - Billing events Read-only and reviewer roles can view permitted audit events. Full audit access requires Risk Manager, Tenant Admin, or Tenant Owner role. --- ## Tips for a healthy register - **Write clear risk titles** — a good title names what can go wrong and in what context - **Don't skip the knowledge field** — it is where context, evidence, and background live; it makes reviews faster - **Set residual risk honestly** — residual score is your judgment; it should reflect how confident you are in the controls actually working - **Review overdue risks first** — filter by `overdue_only` to see what needs attention immediately - **Keep controls specific** — vague controls like "follow procedure" are hard to verify; name the procedure and the frequency - **Use groups** — risk groups make filtering and targeted sharing much easier - **Archive, don't delete** — archived risks are retained for reference and audit history - **Rotate MCP keys periodically** — treat MCP API keys like passwords; revoke and recreate them if they may have been exposed --- ## HSE NZ/AU Skills — companion skill collection The [`scottmss/hse-nz-au-skills`](https://github.com/scottmss/hse-nz-au-skills) repository is an open-source collection of Claude Agent Skills that extend what your AI can do in the HSE domain. These skills are designed to pair naturally with Risk3y — they produce portable Markdown output (bow-ties, task analyses, control-assurance views, reviews) that you store and maintain in your Risk3y register. > The skills are a reasoning and drafting layer. Risk3y is where you record and maintain the output. ### What the collection covers 31 skills spanning NZ and Australian HSE law, critical-risk methodology, incident investigation, and a full tier of hazard subject-matter experts: | Skill | Purpose | | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `hse-advisor` | Orchestrator — identifies jurisdiction (NZ vs AU) and routes to the right specialist | | `critical-risk-manager` | Builds and reviews bow-tie risk assessments, scores control assurance and residual risk | | `prosecution-analyst` | Turns NZ/AU prosecution patterns into preventive lessons — can connect to Risk3y's prosecution database via MCP | | `worksafe-nz-specialist` | NZ HSWA 2015 duties, PCBU obligations, notifiable events, overlapping duties | | `safework-au-specialist` | Australian WHS law, PCBU primary duty, officer due diligence, notifiable incidents | | `officer-governance-advisor` | Officer/board H&S governance and due diligence (HSWA s 44) | | `incident-investigator` | Structured Five Whys root-cause analysis for workplace incidents and near-misses | | `sop-author` | Writes or reviews Standard Operating Procedures / safe systems of work | | `task-analysis-author` | Builds a Task Analysis / JSA — steps, hazards, controls (hierarchy), residual risk | | `working-at-height-specialist` | Falls prevention, dropped objects, rescue, NZ/AU guidance | | `excavation-specialist` | Trenching, underground services, collapse prevention, NZ/AU guidance | | `confined-space-specialist` | Entry permits, atmosphere testing, standby, rescue | | `machinery-safety-specialist` | Guarding, LOTO/isolation, emergency stops | | `mobile-plant-traffic-specialist` | Vehicle/pedestrian separation, traffic management plans | | `lifting-rigging-specialist` | Rigging method, sling selection, load estimation, lift planning | | `crane-specialist` | Crane selection, load chart, outrigger set-up, critical-lift classification | | `forklift-specialist` | Rated capacity, stability triangle, pedestrian separation, pre-start | | `hazardous-substances-specialist` | SDS/GHS, controls hierarchy, NZ/AU regs | | `electrical-energy-specialist` | Isolation, arc flash, overhead-line distances, hot work | | `psychosocial-risk-specialist` | Work-design hazards, psychosocial controls, NZ/AU split | | `high-risk-work-specialist` | Licences and competencies for high-risk work (AU HRWL / NZ CoC) | | `construction-specialist` | Principal contractor, SWMS, temporary works, demolition, precast | | `forestry-specialist` | Tree felling, cable logging, winch-assist, competency, remote rescue | | `agriculture-specialist` | Farm vehicles, quad bikes, livestock, working alone, child safety | | `horticulture-specialist` | Orchard MEWPs, spray-drift, packhouse machinery, coolstores | | `transport-logistics-specialist` | Chain of Responsibility, driver fatigue, load restraint | | `manufacturing-specialist` | Process safety, combustible dust, occupational noise, manual tasks | | `stevedoring-specialist` | Port cargo-handling, plant-pedestrian interface, lashing-at-height | | `water-safety-specialist` | Working in/on/above water, lifejackets, diving | | `violence-aggression-specialist` | Work-related violence, lone-worker controls, de-escalation | | `complex-problem-analyst` | Fishbone (Ishikawa) analysis for multi-causal problems | ### How it pairs with Risk3y **Typical workflow:** 1. Use `hse-advisor` or a specialist skill to draft a bow-tie, task analysis, or control set. 2. Ask `prosecution-analyst` to ground the analysis in real enforcement patterns — it can query Risk3y's prosecution database via MCP. 3. Review and validate the output with a competent practitioner. 4. Record the approved risk, controls, and knowledge in your Risk3y register. 5. Use Risk3y's review and sharing features to keep the register alive. ### Installing the skills **Claude Code (recommended):** ``` /plugin marketplace add scottmss/hse-nz-au-skills ``` **Or install the bundle:** ``` /plugin install hse-core@hse-nz-au-skills ``` **Claude.ai / API:** Download individual skill zips from the [GitHub Releases page](https://github.com/scottmss/hse-nz-au-skills/releases) and upload via Settings → Capabilities → Skills. The whole collection is also available as `hse-nz-au-skills.zip`. **Manual install (single skill):** ```bash git clone https://github.com/scottmss/hse-nz-au-skills.git cp -r hse-nz-au-skills/skills/critical-risk-manager ~/.claude/skills/ ``` ### Important disclaimer These skills produce drafting, structure, and analysis — **not legal advice**. Every output must be reviewed and validated by a competent HSE practitioner against the actual site, people, and the current text of the law and standards. They are generic and company-agnostic — no organisation-specific process or proprietary content. --- ## Common questions **Can I have more than one organisation?** Yes. You can create and switch between multiple organisations from the workspace switcher — useful for consultants managing multiple clients. **What happens if I exceed my plan limits?** You will see an upgrade prompt. Risk3y does not automatically charge overage. **Can I import an existing spreadsheet?** CSV import is a P1 feature. Currently you can add risks manually or via MCP. Export to CSV is available now. **Can I change my risk matrix after I have scored risks?** Yes. Changing matrix labels or levels does not delete scored risks, but existing scores will reflect the new level definitions on recalculation. Plan changes carefully if you have a live register. **Who can see public share links?** Anyone with the link. You can optionally add a password or an expiry date, and you can revoke it at any time. **Is my data shared with any AI provider?** No. Risk3y does not send your data to any AI provider. If you connect an AI tool via MCP, that connection is between your AI client and your Risk3y tenant — Risk3y does not forward data externally. **What is the difference between Simple and Advanced register mode?** Simple mode gives you a clean, focused risk list. Advanced mode adds structured threats, top event (bow-tie hinge), bow-tie control wiring, job role ownership, and education methods. Solo plan is locked to Simple.