Bow Tie Kreative Writing System
Run the engine

Rules / technical writing

TEC-008 Context default layer: section

Recovery follows known failure

IF a step has a common or consequential failure mode, THEN provide symptom, cause or check, corrective action, and verification ELSE retain.

Why the rule exists

Recovery content is part of task completion, not an optional appendix.

Condition

The rule fires when this evaluates true. Paths marked below must be present in the fact base; the engine reports the rest rather than guessing them.

  • ALL
    • task_step.failure_mode.exists eq true
    • ANY
      • task_step.failure_mode.frequency in [common, intermittent]
      • task_step.failure_mode.consequence in [high, critical]

Facts this rule reads

PathSource
task_step.failure_mode.exists You supply it
task_step.failure_mode.frequency You supply it
task_step.failure_mode.consequence You supply it

Then

  1. insert — target task_step.recovery

Else

  1. retain — target current_text, No triggering condition is present.

LAKA

Smallest sufficient intervention
Yes
Primary axes

Sources

  • DITA 1.3 Technical Content Specification — OASIS link
    Topic-based concept, task, reference, troubleshooting, and reuse architecture.
  • The Insider's Guide to Technical Writing — Krista Van Laan
    Documentation practice, careers, projects, and users.
  • Developing Quality Technical Information — Michelle Carey; Moira Lanyi; Deirdre Longo; et al.
    Quality dimensions for usable technical information.
The raw rule record

Verbatim from 15-technical-writing-rules.json. Also available at /v1/rules/TEC-008.

{
  "id": "TEC-008",
  "name": "Recovery follows known failure",
  "domain": "technical_writing",
  "layer": "section",
  "strength": "context_default",
  "human_logic": "IF a step has a common or consequential failure mode, THEN provide symptom, cause or check, corrective action, and verification ELSE retain.",
  "when": {
    "all": [
      {
        "path": "task_step.failure_mode.exists",
        "operator": "eq",
        "value": true
      },
      {
        "any": [
          {
            "path": "task_step.failure_mode.frequency",
            "operator": "in",
            "value": [
              "common",
              "intermittent"
            ]
          },
          {
            "path": "task_step.failure_mode.consequence",
            "operator": "in",
            "value": [
              "high",
              "critical"
            ]
          }
        ]
      }
    ]
  },
  "then": [
    {
      "action": "insert",
      "target": "task_step.recovery",
      "include": [
        "symptom",
        "cause_or_check",
        "corrective_action",
        "verification"
      ]
    }
  ],
  "else": [
    {
      "action": "retain",
      "target": "current_text",
      "reason": "No triggering condition is present."
    }
  ],
  "unless": [],
  "because": "Recovery content is part of task completion, not an optional appendix.",
  "diagnostics": [],
  "examples": {},
  "source_ids": [
    "WEB-008",
    "BK-020",
    "BK-024"
  ],
  "laka": {
    "smallest_sufficient_intervention": true,
    "primary_axes": [
      "scope",
      "depth",
      "magnitude",
      "reversibility"
    ]
  }
}

Other technical writing rules

  1. TEC-001 Choose an information type IF a technical topic is being created, THEN classify it as concept, task, reference, troubleshooting, glossary, or mixed with explicit boundaries ELSE do not draft a generic blob. Hard constraint
  2. TEC-002 Concept answers what and why IF the reader asks what something is or why it matters, THEN use a concept topic with definition, model, relationship, boundary, and example ELSE select another type. Context default
  3. TEC-003 Task answers how to achieve a goal IF the reader wants to achieve an outcome, THEN use a task topic with goal, prerequisites, steps, results, recovery, and verification ELSE select another type. Context default
  4. TEC-004 Reference supports lookup IF the reader needs facts about an entity or interface, THEN use stable repeated fields, valid values, defaults, constraints, examples, and links ELSE select another type. Context default
  5. TEC-005 Prerequisites before steps IF a task requires permissions, state, tools, knowledge, inputs, or safety conditions, THEN list them before step 1 ELSE state that none are required only when useful. Hard constraint
  6. TEC-006 Imperative starts the step IF the reader performs a procedural action, THEN start with a specific imperative verb and name the object ELSE name the actual actor. Context default
  7. TEC-007 Expected result follows uncertain action IF a step’s success is not self-evident, THEN state the observable result immediately after it ELSE retain. Context default
  8. TEC-009 Troubleshooting begins with observable symptom IF troubleshooting advice begins with an assumed cause, THEN reframe from the user-observable symptom and branch by tests ELSE retain. Hard constraint