8D Tools

A command-line tool for generating Eight Disciplines (8D) problem-solving reports from customizable templates, inspired by the ADR-tools pattern.

What is 8D?

The Eight Disciplines (8D) is a problem-solving methodology designed to find the root cause of a problem, devise a short-term fix and implement a long-term solution to prevent recurring problems. Originally developed by Ford Motor Company, it's widely used in manufacturing and quality management.

The eight disciplines are:

• D0: Plan and prepare
• D1: Form a team
• D2: Identify the problem
• D3: Develop interim containment plan
• D4: Verify root causes and escape points
• D5: Choose permanent corrective actions
• D6: Implement corrective actions
• D7: Take preventive measures
• D8: Celebrate with your team

Installation

Global Installation

npm install -g @zanozbot/8d-tools

Using without Installation

You can also use 8d-tools directly without installing it globally:

With npx (Node.js):

npx @zanozbot/8d-tools <command>

With bunx (Bun):

bunx @zanozbot/8d-tools <command>

Quick Start

With Global Installation

1. Initialize 8D directory structure:

   8d init

2. Create your first 8D report:

   8d new "Product Quality Issue"

3. View help for all commands:

   8d help

With npx/bunx (No Installation Required)

1. Initialize 8D directory structure:

   npx @zanozbot/8d-tools init
   # or
   bunx @zanozbot/8d-tools init

2. Create your first 8D report:

   npx @zanozbot/8d-tools new "Product Quality Issue"
   # or
   bunx @zanozbot/8d-tools new "Product Quality Issue"

3. View help for all commands:

   npx @zanozbot/8d-tools help
   # or
   bunx @zanozbot/8d-tools help

For detailed usage instructions, see docs/USAGE.md.

Commands

8d help

Shows comprehensive help information with examples.

8d init [directory]

Initializes the 8D directory structure.

Arguments:

• directory (optional): Directory for 8D reports (default: docs/8d)

Creates:

• .8d-dir file pointing to the 8D directory
• 8D directory with .8d-sequence.lock file
• Table of contents (README.md)

Examples:

# With global installation
8d init                    # Initialize in docs/8d
8d init reports/8d         # Initialize in custom directory

# With npx/bunx
npx @zanozbot/8d-tools init
bunx @zanozbot/8d-tools init reports/8d

8d new <title> [options]

Creates a new 8D report with sequential numbering.

Arguments:

• title: Title of the 8D report

Options:

• -s, --supersede <number>: Supersede an existing 8D report
• -l, --link <link>: Link to existing report (format: "number:LinkType:ReverseLink")
• -t, --template <name>: Template to use (default: "default")

Examples:

# With global installation
8d new "Product Quality Issue"
8d new "Updated Process" -s 3
8d new "Related Issue" -l "2:Related to:Related to"
8d new "Simple incident" -t simple

# With npx/bunx
npx @zanozbot/8d-tools new "Product Quality Issue"
bunx @zanozbot/8d-tools new "Updated Process" -s 3

8d link <source> <target> [linkType]

Links two existing 8D reports.

Arguments:

• source: Source 8D report number
• target: Target 8D report number
• linkType (optional): Type of link (default: "Supersedes")

Examples:

# With global installation
8d link 1 2              # Uses default "Supersedes"
8d link 1 2 "Related to"
8d link 3 4 "Supersedes"

# With npx/bunx
npx @zanozbot/8d-tools link 1 2
bunx @zanozbot/8d-tools link 1 2 "Related to"

8d template [action] [name] [options]

Manage 8D report templates.

Actions:

• list: List all available templates
• create <name>: Create a new custom template
• show <name>: Display template content
• delete <name>: Delete a custom template

Options for create:

• --title <title>: Set a custom title (default: uses {{title}} placeholder)

Examples:

# With global installation
8d template list                                    # List all templates
8d template create incident                         # Create template with {{title}} placeholder
8d template create security --title "Security Incident"  # Create with fixed title
8d template show simple                             # Display simple template
8d template delete incident                         # Delete custom template

# With npx/bunx
npx @zanozbot/8d-tools template list
bunx @zanozbot/8d-tools template create incident
bunx @zanozbot/8d-tools template show simple

File Structure

After initialization, your project will have:

project-root/
├── .8d-dir                    # Points to 8D directory
└── docs/8d/                   # Default 8D directory
    ├── .8d-sequence.lock      # Tracks sequence numbers
    ├── .templates/            # Custom templates directory
    │   ├── incident.md        # Custom incident template
    │   └── security.md        # Custom security template
    ├── README.md              # Table of contents
    ├── 0001-first-issue.md    # First 8D report
    └── 0002-second-issue.md   # Second 8D report

Templates

8D-tools supports multiple templates to suit different problem-solving needs:

Built-in Templates

Default Template (default)

The comprehensive 8D template covering all eight disciplines:

• Header: Title, date, status, and links
• D0: Planning and preparation
• D1: Team formation
• D2: Problem identification with 5W2H analysis
• D3: Interim containment planning
• D4: Root cause analysis and escape points
• D5: Permanent corrective action selection
• D6: Implementation planning
• D7: Preventive measures
• D8: Team celebration and lessons learned

Simple Template (simple)

A streamlined template for quick problem-solving that follows the full 8D structure with simplified content:

• Header: Title, date, status, and links
• D0: Planning and preparation
• D1: Team members (simplified table format)
• D2: Problem statement and description
• D3: Interim containment action
• D4: Root cause and escape points
• D5: Permanent corrective action
• D6: Implementation plan
• D7: Preventive measures
• D8: Review and closure

Using Templates

# With global installation
8d new "Complex Quality Issue"              # Use default template (comprehensive 8D)
8d new "Simple incident" -t simple          # Use simple template (streamlined)
8d template list                            # List available templates

# With npx/bunx
npx @zanozbot/8d-tools new "Complex Quality Issue"
bunx @zanozbot/8d-tools new "Simple incident" -t simple
npx @zanozbot/8d-tools template list

Custom Templates

You can create custom templates for specific use cases:

# With global installation
8d template create incident                         # Create a new custom template
8d template create security --title "Security Incident Report"  # Create with a fixed title
8d template show incident                           # View template content
8d template delete incident                         # Delete custom template

# With npx/bunx
npx @zanozbot/8d-tools template create incident
bunx @zanozbot/8d-tools template create security --title "Security Incident Report"
npx @zanozbot/8d-tools template show incident

Template Placeholders

Custom templates support these placeholders:

• {{title}}: Report title
• {{sequence}}: Report sequence number for titles (e.g., "1", "2", "3")
• {{date}}: Creation date
• {{links}}: Links section (automatically populated)

Note: Filenames use zero-padded sequence numbers (0001, 0002, etc.) while titles use simple numbers (1, 2, 3).

Example Custom Template

# {{title}}

**Date:** {{date}}
**Status:** Draft
{{links}}

## Incident Summary

<!-- Brief description of the incident -->

## Impact Assessment

<!-- What was affected and how -->

## Timeline

<!-- Chronological sequence of events -->

## Root Cause

<!-- Primary cause of the incident -->

## Resolution

<!-- Steps taken to resolve -->

## Follow-up Actions

<!-- Preventive measures and monitoring -->

Linking Reports

8D-tools supports linking related reports with automatic bidirectional linking:

Superseding Reports

# With global installation
8d new "Updated Solution" -s 3

# With npx/bunx
npx @zanozbot/8d-tools new "Updated Solution" -s 3

This creates a new report that supersedes report #3, automatically adding:

• "Supersedes" link in the new report
• "Superseded by" link in report #3

Custom Links

# With global installation
8d new "Related Analysis" -l "2:Amends:Amended by"

# With npx/bunx
npx @zanozbot/8d-tools new "Related Analysis" -l "2:Amends:Amended by"

This creates links:

• "Amends" link in the new report pointing to #2
• "Amended by" link in report #2 pointing to the new report

Manual Linking

# With global installation
8d link 1 4 "Related to"

# With npx/bunx
npx @zanozbot/8d-tools link 1 4 "Related to"

This adds bidirectional "Related to" links between reports #1 and #4.

Best Practices

1. Use descriptive titles that clearly identify the problem
2. Initialize once per project - the tool tracks the 8D directory location
3. Link related reports to maintain traceability
4. Follow the 8D process systematically through each discipline
5. Update status as you progress through the problem-solving process

Development

Building

npm run prepack

Testing

npm test

Type Checking

npm run types:check

License

GPL-3.0

Contributing

Issues and pull requests are welcome on GitHub.