Skip to content

USAGE.md

Latest commit

 

History

History
426 lines (320 loc) · 8.99 KB

USAGE.md

File metadata and controls

426 lines (320 loc) · 8.99 KB

8D Tools Usage Guide

This comprehensive guide covers all aspects of using 8d-tools for effective problem-solving documentation.

Table of Contents

Getting Started

Installation Options

Option 1: Global Installation (Recommended)

npm install -g @zanozbot/8d-tools

Option 2: Use without Installation

# With npx (Node.js)
npx @zanozbot/8d-tools <command>

# With bunx (Bun)
bunx @zanozbot/8d-tools <command>

First Steps

  1. Initialize your 8D workspace:

    8d init
# or specify custom directory
8d init reports/quality-issues

  2. Create your first report:

    8d new "Product Quality Issue"

  3. View the generated files:

    ls docs/8d/
cat docs/8d/0001-product-quality-issue.md

Basic Workflow

1. Problem Identification

When a problem occurs, start by creating a new 8D report:

8d new "Manufacturing Defect - Adhesive Bond Failure"

This creates:

  • A new report file: 0001-manufacturing-defect-adhesive-bond-failure.md
  • Updates the table of contents
  • Assigns the next sequence number

2. Choose the Right Template

For complex problems requiring full 8D methodology:

8d new "Complex Quality Issue" -t default

For quick incidents or simple problems:

8d new "Server Downtime" -t simple

For specific use cases with custom templates:

8d new "Security Incident" -t security

3. Link Related Reports

When superseding an old report:

8d new "Updated Process Documentation" -s 3

When creating related reports:

8d new "Follow-up Investigation" -l "2:Related to:Related to"

Link existing reports:

8d link 1 2 "Supersedes"

Command Reference

8d init [directory]

Initializes the 8D directory structure.

Parameters:

  • directory (optional): Target directory (default: docs/8d)

Examples:

8d init                    # Creates docs/8d/
8d init quality/8d         # Creates quality/8d/
8d init /path/to/reports   # Creates absolute path

What it creates:

  • .8d-dir file (points to 8D directory)
  • 8D directory with .8d-sequence.lock
  • README.md (table of contents)
  • .templates/ directory for custom templates

8d new <title> [options]

Creates a new 8D report.

Parameters:

  • title: Report title (required)

Options:

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

Examples:

# Basic report
8d new "Quality Issue"

# With specific template
8d new "Quick Fix" -t simple

# Superseding report #3
8d new "Updated Solution" -s 3

# Linked report
8d new "Related Issue" -l "1:Related to:Related to"

Link Format: "<target_number>:<link_type>:<reverse_link_type>"

Common link types:

  • Supersedes ↔ Superseded by
  • Related to ↔ Related to
  • Amends ↔ Amended by
  • Clarifies ↔ Clarified by

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

Links two existing reports.

Parameters:

  • source: Source report number
  • target: Target report number
  • linkType (optional): Link type (default: "Supersedes")

Examples:

8d link 1 2              # 1 supersedes 2
8d link 1 2 "Related to" # 1 related to 2
8d link 3 4 "Amends"     # 3 amends 4

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

Manage templates.

Actions:

  • list: Show all available templates
  • create <name>: Create new custom template
  • show <name>: Display template content
  • delete <name>: Remove custom template

Examples:

8d template list
8d template create incident
8d template show simple
8d template delete old-template

Templates

Built-in Templates

Default Template

Comprehensive 8D methodology covering all disciplines:

  • Complete problem analysis (5W2H)
  • Team formation and charter
  • Root cause analysis
  • Solution evaluation
  • Implementation planning
  • Preventive measures

Simple Template

Streamlined for quick incidents:

  • Essential 8D structure
  • Simplified sections
  • Faster completion
  • Suitable for minor issues

Custom Templates

Create templates for specific use cases:

8d template create security --title "Security Incident Report"

Template Placeholders:

  • {{title}}: Report title
  • {{sequence}}: Sequence number (1, 2, 3...)
  • {{date}}: Creation date
  • {{links}}: Links section

Example Custom Template:

# {{title}}

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

## Incident Summary
<!-- Brief description -->

## Impact Assessment
<!-- What was affected -->

## Timeline
<!-- Sequence of events -->

Linking Reports

Automatic Linking

Superseding Reports:

8d new "Updated Process" -s 2
  • Creates new report that supersedes #2
  • Adds "Supersedes" link to new report
  • Adds "Superseded by" link to report #2

Related Reports:

8d new "Follow-up" -l "1:Related to:Related to"
  • Creates bidirectional "Related to" links

Manual Linking

Link existing reports after creation:

8d link 1 3 "Clarifies"

Link Types

Choose appropriate link types:

  • Supersedes/Superseded by: New version replaces old
  • Related to: Connected but independent issues
  • Amends/Amended by: Corrections or additions
  • Clarifies/Clarified by: Explanations or details
  • Extends/Extended by: Builds upon previous work

File Organization

Directory Structure

project-root/
├── .8d-dir                    # Points to 8D directory
└── docs/8d/                   # Default 8D directory
    ├── .8d-sequence.lock      # Sequence tracking
    ├── .templates/            # Custom templates
    ├── README.md              # Table of contents
    ├── 0001-first-issue.md    # Reports with zero-padded numbers
    └── 0002-second-issue.md

File Naming Convention

Filenames: Zero-padded sequence numbers

  • 0001-product-quality-issue.md
  • 0002-server-downtime-incident.md
  • 0010-customer-complaint.md

Titles: Simple numbers

  • # 1: Product Quality Issue
  • # 2: Server Downtime Incident
  • # 10: Customer Complaint

Table of Contents

Automatically maintained in README.md:

## Reports

- [1: Product Quality Issue](./0001-product-quality-issue.md)
- [2: Server Downtime](./0002-server-downtime.md)

Best Practices

Report Creation

  1. Use descriptive titles:

    # Good
8d new "Manufacturing Line 3 - Adhesive Bond Failure in Product X"

# Avoid
8d new "Problem"

  2. Choose appropriate templates:

    • Use default for complex quality issues
    • Use simple for quick incidents
    • Create custom templates for recurring scenarios

  3. Link related reports:

    8d new "Root Cause Analysis" -l "1:Extends:Extended by"

Documentation

  1. Complete all sections systematically
  2. Use data and evidence to support findings
  3. Include photos, charts, and measurements
  4. Document lessons learned
  5. Update status as work progresses

Team Collaboration

  1. Define clear roles and responsibilities
  2. Set realistic timelines
  3. Regular progress reviews
  4. Share knowledge across teams

Advanced Usage

Batch Operations

Create multiple related reports:

8d new "Initial Investigation" -t simple
8d new "Detailed Analysis" -l "1:Extends:Extended by"
8d new "Implementation Plan" -l "2:Follows:Followed by"

Custom Workflows

For recurring problem types, create:

  1. Custom templates
  2. Standard linking patterns
  3. Documented procedures

Integration

8d-tools works well with:

  • Version control systems (Git)
  • Documentation platforms
  • Quality management systems
  • Issue tracking tools

Troubleshooting

Common Issues

"8D directory not initialized"

8d init

"Template not found"

8d template list  # Check available templates

"Report number not found" (for linking)

ls docs/8d/       # Check existing reports
cat docs/8d/README.md  # View table of contents

Permission errors

# Check directory permissions
ls -la docs/8d/
# Or initialize in different location
8d init ~/my-8d-reports

Getting Help

8d help                # General help
8d new --help          # Command-specific help
8d template --help     # Template management help
8d link --help         # Linking help

Support

For more examples and detailed scenarios, see the examples directory.