docs: document process-level parallel linting capability

Add documentation for existing parallel linting capability using the
linter binary's individual file type arguments.

Changes:
- Add scripts/lint-parallel.sh demonstrating parallel execution
- Update linter-parallel-execution feature docs with process-level approach
- Document performance comparison (15s sequential vs 14s parallel)
- Explain why minimal gain (clippy dominates at ~12s/80% of time)
- Add parallel execution section to linting.md with usage guidance
- Recommend sequential execution for clean output in regular development

Key findings:
- Process-level parallelization already possible via CLI arguments
- Only ~1s (7%) performance gain due to clippy domination
- Trade-off: minimal speedup vs potentially interleaved output
- Confirms decision to defer complex code-level implementation

Author: josecelano

docs/contributing/linting.md

@@ -70,6 +70,24 @@ cargo run --bin linter shellcheck
 ./scripts/linting/shellcheck.sh
 ```
 
+### Parallel Execution (Experimental)
+
+For scenarios where you want to run linters concurrently:
+
+```bash
+# Run linters in parallel using process-level parallelization
+./scripts/lint-parallel.sh
+```
+
+**Note**: Parallel execution provides minimal performance improvement (~1s, 7% faster) and may produce interleaved output. Sequential execution is recommended for regular development.
+
+**When to use**:
+
+- ✅ CI/CD pipelines where every second counts
+- ❌ Regular development (use sequential for clean output)
+
+See [Linter Parallel Execution Feature](../features/linter-parallel-execution/README.md) for detailed analysis and trade-offs.
+
 ## 📋 Tool-Specific Guidelines
 
 ### Markdown Linting (`markdownlint-cli`)
@@ -352,11 +370,26 @@ rustup component add clippy rustfmt
 
 ```bash
 # Run specific linters for faster feedback during development
-cargo run --bin linter markdown    # Only markdown (fastest)
-cargo run --bin linter yaml        # Only YAML files
-cargo run --bin linter clippy      # Only Rust analysis (slowest)
+cargo run --bin linter markdown    # Only markdown (~1s)
+cargo run --bin linter yaml        # Only YAML files (~0.2s)
+cargo run --bin linter clippy      # Only Rust analysis (~12s - slowest)
+
+# Run non-Rust linters for quick checks
+cargo run --bin linter markdown
+cargo run --bin linter yaml
+cargo run --bin linter toml
+# Skip clippy for faster iteration during active development
 ```
 
+**Parallel execution** is also possible but provides minimal benefit:
+
+```bash
+# Process-level parallelization (experimental, ~1s faster)
+./scripts/lint-parallel.sh
+```
+
+Note: Parallel execution trades clean output for minimal speed gain. Use sequential execution for regular development.
+
 ## 🚨 Troubleshooting
 
 ### Common Issues

docs/features/linter-parallel-execution/README.md

@@ -36,7 +36,46 @@ Clarifying questions for implementation (if feature is prioritized in the future
 
 **Status**: **Deferred** - Not a priority for initial implementation
 
-**Reason**: Current performance (13s) is acceptable for pre-commit workflow. Implementation complexity outweighs performance gains.
+**Reason**: Current performance (15s) is acceptable for pre-commit workflow. Implementation complexity outweighs minimal performance gains.
+
+**Reconsider when**: Execution time exceeds **25 seconds** (more linters added) or auto-fix feature makes it too slow.
+
+## ✅ Alternative: Process-Level Parallelization (Already Possible)
+
+**Discovery**: The linter binary already supports running individual linter types via command-line arguments, which enables **process-level parallelization** without code changes.
+
+**Script Location**: `scripts/lint-parallel.sh`
+
+**How it works**:
+
+```bash
+# Run individual linters in parallel processes
+./target/release/linter markdown &
+./target/release/linter yaml &
+./target/release/linter toml &
+./target/release/linter shellcheck &
+./target/release/linter rustfmt &
+wait
+
+# Run clippy sequentially (may conflict with rustfmt)
+./target/release/linter clippy
+
+# Run cspell separately (read-only)
+./target/release/linter cspell
+```
+
+**Performance**: ~14s (vs 15s sequential) - minimal improvement due to clippy dominating execution time (~12s)
+
+**Trade-offs**:
+
+- ✅ No code changes required
+- ✅ Simple shell script implementation
+- ✅ Easy to adjust grouping strategy
+- ❌ Output may be interleaved (less readable)
+- ❌ Minimal performance gain (~1s) since clippy dominates
+- ❌ Less control over error aggregation and reporting
+
+**Recommendation**: Use sequential execution (`cargo run --bin linter all`) for clean output. Process-level parallelization provides minimal benefit and potentially confusing output.
 
 **Reconsider when**: Execution time exceeds **25 seconds** (more linters added) or auto-fix feature makes it too slow.
 

docs/features/linter-parallel-execution/specification.md

@@ -358,11 +358,130 @@ If/when this feature is implemented:
 - [Development Principles](../../development-principles.md)
 - [Linting Guide](../../contributing/linting.md)
 
-## 📊 Priority
+## � Alternative Approach: Process-Level Parallelization
+
+### Discovery: Existing CLI Support
+
+The linter binary already supports running individual linter types via command-line arguments:
+
+```bash
+cargo run --bin linter markdown
+cargo run --bin linter yaml
+cargo run --bin linter toml
+cargo run --bin linter clippy
+cargo run --bin linter rustfmt
+cargo run --bin linter shellcheck
+cargo run --bin linter cspell
+```
+
+This enables **process-level parallelization** without any code changes - simply run multiple linter processes concurrently using shell job control.
+
+### Implementation: Shell Script
+
+**Location**: `scripts/lint-parallel.sh`
+
+**Approach**:
+
+```bash
+#!/bin/bash
+
+# Build once in release mode for better performance
+cargo build --release --bin linter --quiet
+LINTER_BIN="./target/release/linter"
+
+# Group 1: Run linters in parallel (different file types)
+"$LINTER_BIN" markdown &
+"$LINTER_BIN" yaml &
+"$LINTER_BIN" toml &
+"$LINTER_BIN" shellcheck &
+"$LINTER_BIN" rustfmt &
+wait
+
+# Group 2: Run clippy sequentially
+"$LINTER_BIN" clippy
+
+# Separate: Run cspell (read-only)
+"$LINTER_BIN" cspell
+```
+
+### Performance Comparison
+
+**Sequential execution** (`cargo run --bin linter all`):
+
+- Total time: ~15 seconds
+- Output: Clean, grouped by linter
+- All errors displayed in logical order
+
+**Process-level parallel execution** (`./scripts/lint-parallel.sh`):
+
+- Total time: ~14 seconds (7% faster)
+- Output: May be interleaved from concurrent processes
+- Limited improvement because clippy dominates (~12s out of 15s)
+
+### Why Minimal Performance Gain?
+
+**Execution time breakdown**:
+
+- clippy: ~12s (80% of total time) - runs sequentially
+- markdown: ~1s
+- yaml: ~0.15s
+- toml: ~0.07s
+- rustfmt: ~0.2s
+- shellcheck: ~0.03s
+- cspell: ~1.6s
+
+**Analysis**: Clippy dominates execution time, so parallelizing the other fast linters (~3s combined) only saves ~1 second.
+
+**Theoretical maximum speedup**: Even if all non-clippy linters ran instantly, total time would be ~12s (clippy) + ~0s (others) = ~12s, only ~3s improvement from current 15s.
+
+### Trade-offs: Process-Level vs Code-Level Parallelization
+
+| Aspect               | Process-Level (Shell Script) | Code-Level (Async Refactor)           |
+| -------------------- | ---------------------------- | ------------------------------------- |
+| **Implementation**   | ✅ Simple shell script       | ❌ Complex async refactoring          |
+| **Code changes**     | ✅ None required             | ❌ All 7 linters need refactoring     |
+| **Performance gain** | ⚠️ Minimal (~1s, 7%)         | ⚠️ Similar (~1-2s at best)            |
+| **Output quality**   | ❌ May be interleaved        | ✅ Clean, sequential display          |
+| **Error handling**   | ❌ Basic process exit codes  | ✅ Rich error aggregation             |
+| **Maintenance**      | ✅ Easy to modify            | ❌ More complex to maintain           |
+| **Testing**          | ✅ Simple to test            | ❌ Requires async test infrastructure |
+| **Dependencies**     | ✅ None                      | ❌ Adds tokio/async runtime           |
+
+### Recommendation
+
+**Use sequential execution** (`cargo run --bin linter all`) because:
+
+1. **Clean output**: Errors are grouped by linter and easy to read
+2. **Minimal speedup**: Process-level parallelization only saves ~1s (7%)
+3. **Simplicity**: No additional scripts or complexity needed
+4. **Maintenance**: One less thing to maintain
+
+**When to use process-level parallelization**:
+
+- Never recommended for regular development workflow
+- Could be useful for CI/CD if every second counts (but 1s is negligible)
+- Better to wait for more linters to be added (if ever) before optimizing
+
+**When to implement code-level parallelization**:
+
+- Execution time exceeds 25 seconds (more linters added)
+- Clippy execution time is significantly reduced
+- Auto-fix feature makes linting much slower
+
+### Conclusion
+
+The discovery that process-level parallelization is already possible **confirms the initial decision** to defer implementation:
+
+- ✅ Minimal performance gain even with perfect parallelization
+- ✅ Clean sequential output is more valuable than 1s speedup
+- ✅ No compelling reason to add complexity
+- ✅ YAGNI principle applies - implement only if truly needed
+
+## �📊 Priority
 
 **Priority**: Low (Future Enhancement)
 
-**Reason**: Current performance is acceptable. Focus on higher-value features first (like auto-fix).
+**Reason**: Current performance (15s) is acceptable. Process-level parallelization available but provides minimal benefit (1s). Focus on higher-value features first (like auto-fix).
 
 **Decision**: Defer implementation until there's clear evidence it's needed.
 

scripts/lint-parallel.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+
+# Parallel Linting Script
+#
+# This script demonstrates running linters in parallel by calling the linter binary
+# with individual file type arguments. Each linter runs in a separate process.
+#
+# Usage: ./scripts/lint-parallel.sh
+#
+# This approach provides parallel execution without modifying the linter binary,
+# but has trade-offs:
+#
+# Pros:
+# - No code changes required - uses existing CLI interface
+# - Simple to implement and understand
+# - Real parallel execution with performance gains
+# - Easy to adjust grouping strategy
+#
+# Cons:
+# - Output may be interleaved (mixed messages from different linters)
+# - Multiple Rust compilation/startup overhead if binary not cached
+# - Less control over output formatting
+# - Harder to aggregate errors cleanly
+
+set -e
+
+echo "========================================"
+echo "Running Linters in Parallel"
+echo "========================================"
+echo ""
+
+# Build the linter binary once (release mode for better performance)
+echo "Building linter binary..."
+cargo build --release --bin linter --quiet
+LINTER_BIN="./target/release/linter"
+
+echo ""
+
+# Track overall success/failure
+FAILED=0
+
+# Temporary directory for storing results
+RESULT_DIR=$(mktemp -d)
+trap 'rm -rf "$RESULT_DIR"' EXIT
+
+# Function to run a linter and capture its exit code
+run_linter() {
+    local linter_name=$1
+    local result_file="$RESULT_DIR/$linter_name.result"
+    
+    echo "Starting $linter_name linter..."
+    
+    if "$LINTER_BIN" "$linter_name" > "$result_file.log" 2>&1; then
+        echo "0" > "$result_file"
+        echo "✓ $linter_name completed successfully"
+    else
+        echo "1" > "$result_file"
+        echo "✗ $linter_name failed"
+    fi
+}
+
+# Start timing
+START_TIME=$(date +%s)
+
+# Group 1: Run linters in parallel (different file types - no conflicts)
+echo "Group 1: Running linters in parallel (markdown, yaml, toml, shellcheck, rustfmt)..."
+echo ""
+
+run_linter "markdown" &
+PID_MARKDOWN=$!
+
+run_linter "yaml" &
+PID_YAML=$!
+
+run_linter "toml" &
+PID_TOML=$!
+
+run_linter "shellcheck" &
+PID_SHELLCHECK=$!
+
+run_linter "rustfmt" &
+PID_RUSTFMT=$!
+
+# Wait for Group 1 to complete
+wait $PID_MARKDOWN $PID_YAML $PID_TOML $PID_SHELLCHECK $PID_RUSTFMT
+
+echo ""
+echo "Group 1 completed."
+echo ""
+
+# Group 2: Run clippy sequentially (may conflict with rustfmt on .rs files)
+echo "Group 2: Running clippy (sequential)..."
+echo ""
+
+run_linter "clippy"
+
+echo ""
+echo "Group 2 completed."
+echo ""
+
+# Separate group: Run cspell (checks all files, read-only)
+echo "Running cspell (read-only checker)..."
+echo ""
+
+run_linter "cspell"
+
+echo ""
+
+# Calculate elapsed time
+END_TIME=$(date +%s)
+ELAPSED=$((END_TIME - START_TIME))
+
+# Display results
+echo ""
+echo "========================================"
+echo "Linting Results"
+echo "========================================"
+echo ""
+
+for linter in markdown yaml toml shellcheck rustfmt clippy cspell; do
+    result_file="$RESULT_DIR/$linter.result"
+    log_file="$RESULT_DIR/$linter.result.log"
+    
+    if [ -f "$result_file" ]; then
+        exit_code=$(cat "$result_file")
+        if [ "$exit_code" -eq 0 ]; then
+            echo "✓ $linter: PASSED"
+        else
+            echo "✗ $linter: FAILED"
+            FAILED=1
+            
+            # Show the error log
+            if [ -f "$log_file" ]; then
+                echo "  Log:"
+                sed 's/^/    /' "$log_file"
+            fi
+        fi
+    fi
+done
+
+echo ""
+echo "========================================"
+echo "Total time: ${ELAPSED}s"
+echo "========================================"
+
+# Exit with error if any linter failed
+if [ $FAILED -eq 1 ]; then
+    echo ""
+    echo "❌ Some linters failed. Please fix the issues above."
+    exit 1
+else
+    echo ""
+    echo "✅ All linters passed!"
+    exit 0
+fi