Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Change-Impact Workflow

Change-impact analysis is the per-PR triage that asks: which pinned requirements does this code change touch, and are the affected tests still passing? It is the daily-cadence analog of the re-conformity workflow — same machinery, run on every PR rather than on every amendment. It is also the workflow that catches the most common pre-MVP failure mode in safety-critical robotics: a routine refactor that quietly invalidates an assumption a tested-against-once safety requirement relied on.
Roboticks is audit-readiness tooling, not a certified toolchain. We assemble the evidence your notified body, certification body, or QA process ingests. We do not replace tool qualification (DO-178C, ISO 26262-8 TCL) and we do not issue conformity assessments. Verify the regulatory interpretations on this page against the standard text and your accredited assessor.

​
What change-impact analysis does

On every PR, the GitHub App:
  1. Computes the file diff.
  2. Maps changed files to the modules they implement.
  3. For each module, looks up the requirements whose acceptance tests exercise that module.
  4. Posts a Check Run summarising the impact.
The Check Run output: 
✓ Roboticks · 12 requirements touched · 12/12 still confirmed

  REQ-014 Protective stop response time      ✓ tests passing
  REQ-021 Encoder reading sanity             ✓ tests passing
  REQ-032 Safe-state on power loss           ✓ tests passing
  REQ-041 PFL upper-arm quasi-static         ✓ tests passing
  …
Or, when a regression has been introduced: 
✗ Roboticks · 12 requirements touched · 11/12 still confirmed · 1 regression

  REQ-014 Protective stop response time      ✓ tests passing
  REQ-021 Encoder reading sanity             ✗ test_encoder_response_under_100ms (was passing on main)
  …
The Check Run is non-blocking by default; configure it to be required for merge in GitHub Branch Protection if you want hard enforcement.

​
Setup

The change-impact analysis runs automatically once the GitHub App is installed and @confirms annotations are in place. No additional configuration required. Optional configuration in roboticks/config.yaml: 
change_impact:
  block_merge_on_regression: true
  block_merge_on_unexpected_impact: false
  notify_on_safety_impact: ["#safety-team"]
  triage_required_for_severity: ["safety"]
block_merge_on_unexpected_impact is the strict mode: any PR that touches a requirement-related module without an explicit triage acknowledgment fails the Check Run. Recommended once the team is comfortable with the workflow; not recommended on day one (initial false-positive volume can be frustrating).

​
How modules map to requirements

The mapping comes from two sources:
  1. Test execution coverage — when a test runs, Roboticks records which source files it loaded and executed. The requirements that test confirms are now known to depend on those files.
  2. Explicit annotation — requirements can declare a realised_by list of module paths: 
    - id: REQ-014
  realised_by:
    - src/safety/estop_controller.cpp
    - src/safety/estop_controller.hpp
    - src/drivers/motor_driver.cpp
The platform combines both — the explicit annotation acts as a forced inclusion even for code paths not yet exercised by tests; the execution-coverage tracking catches modules the annotation missed.

​
Per-PR triage flow

Three outcomes need human handling:
OutcomeAction
Regression — a previously-passing test now failsFix the code. If the requirement’s intended behaviour has legitimately changed, update the requirement and the test together (substantial modification — record the reason).
Unexpected impact — the PR touched a requirement-related module but did not change the requirement-confirming test outcomesTriage: was the impact intentional? Acknowledge with a comment on the PR; the platform records the acknowledgment.
Gap opened — a code change made a previously-covered requirement uncovered (e.g., deleted a test)Either restore coverage or document an acknowledged gap. Acknowledged gaps require documented rationale and surface in the posture dashboard.

​
Safety-impact escalation

For requirements typed safety (and any other types you configure), the workflow can escalate beyond the Check Run:
  • Slack message to a configured channel.
  • Required reviewer added to the PR (e.g., the safety engineer).
  • Block-on-regression for safety requirements specifically, even if other requirement types are non-blocking.
Configure via notify_on_safety_impact and triage_required_for_severity in roboticks/config.yaml.

​
Integration into code review

The change-impact output is the third leg of the code-review stool, alongside the diff itself and any test results:
ElementWhat the reviewer learns
DiffWhat changed
Test resultsWhether the change broke anything we already test
Change-impactWhich previously-defined requirements this change touches — even if all tests still pass
The third leg is the one that catches “I changed the encoder driver and somehow PFL force limits regressed” before it reaches production. Without it, the reviewer is checking what the author thought to test; with it, the platform is checking what the requirement set says matters.

​
Triage hygiene

A few habits make change-impact reviews sustainable:
  • Keep requirement-to-module mappings up to date. When you move a file, update the realised_by. The execution-coverage backstop catches misses, but explicit annotation is faster.
  • Acknowledge unexpected impacts promptly. A growing backlog of un-acknowledged impacts degrades the signal-to-noise.
  • Don’t paper over regressions. Acknowledging a failing safety test as “acknowledged gap” should be a deliberate decision with sign-off, not a routine action.
  • Use the LLM-suggested derivations and triages cautiously. Useful as a draft; the human is the authority.

​
Worked example

A PR refactors the encoder-reading function. The diff touches src/drivers/encoder.cpp and src/drivers/encoder.hpp.
  • Roboticks identifies 4 requirements whose realised_by or execution-coverage includes these files: REQ-014 (protective stop), REQ-021 (encoder sanity), REQ-032 (safe-state on power loss), REQ-041 (PFL upper-arm).
  • Roboticks runs the 11 tests across the 4 requirements.
  • REQ-021’s test_encoder_overflow_handling fails — the refactor moved overflow detection one stack frame deeper and lost a microsecond on the response time.
  • Check Run reports the regression.
  • PR author identifies the cause, restores the overflow handler in the original location, pushes again.
  • Re-run: 11/11 pass. Check Run goes green. PR merges.
Without change-impact, the regression would have landed on main and surfaced (or not) on the next nightly run, by which time the original author may have moved on to another task.

​
Next steps

Traceability audit prep

Pre-audit checklist that catches what change-impact missed.

GitHub Check Runs

The mechanics of the Check Run integration.

Re-conformity workflow

The standards-amendment analog of this PR-time workflow.