# How the Combined Document and Lint Housekeeping Pass Optimizes Pipeline Execution

> Optimize pipeline execution by combining document and lint housekeeping passes. This reduces latency and costs with a graceful fallback for maintained correctness.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: performance
- Published: 2026-07-13

---

**The combined document and lint housekeeping pass eliminates redundant agent startups by merging documentation and linting duties into a single LLM invocation, reducing latency and compute costs while maintaining correctness through a graceful fallback mechanism.**

The `no-mistakes` pipeline typically executes document maintenance and code linting as separate steps, each requiring a cold agent process startup that incurs significant latency and resource overhead. When a repository lacks a deterministic lint command, the combined document and lint housekeeping pass automatically activates to merge these operations into one efficient agent execution, cutting the required LLM invocations from two to one.

## The Problem: Duplicate Agent Startup Costs

In the standard execution flow, the pipeline runs a **document step** to keep documentation accurate and a separate **lint step** to run repository-configured linters. Each step launches its own cold agent process, paying the full cost of agent startup twice. This duplication creates unnecessary latency and doubles the compute expense for housekeeping operations.

## The Solution: Merging Duties into a Single Pass

The optimization activates when the repository does not define a deterministic lint command. In [`internal/pipeline/steps/document.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/document.go), the implementation checks this condition:

```go
combinedLint := sctx.Config.Commands.Lint == "" // true → combine
if combinedLint {
    sctx.Shared.ClearHousekeepingLint()
}

```

When `combinedLint` evaluates to true, the document step incorporates the lint duty by building a combined prompt that includes the `housekeepingLintSection` instructions and switching its purpose to **"housekeeping"**. This merged prompt instructs the agent to analyze both documentation and lint concerns in a single pass.

## Implementation Details

### Building the Combined Prompt

The document step constructs a comprehensive prompt that covers both documentation updates and lint analysis. The agent executes this combined instruction set, returning structured output containing findings for both categories.

### Splitting and Stashing Findings

After the agent completes, the `splitHousekeepingFindings` function separates the results by their `category` field, distinguishing between `documentation` and `lint` findings. The lint-related findings are then serialized and stored in the shared context:

```go
if combinedLint {
    // After agent run
    lintJSON, err := types.MarshalFindingsJSON(lintFindings)
    if err == nil {
        sctx.Shared.SetHousekeepingLint(pipeline.HousekeepingLintResult{
            FindingsJSON: lintJSON,
            Summary:      findings.Summary,
        })
    }
}

```

This stashing mechanism in [`internal/pipeline/shared.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/shared.go) creates a temporary persistence layer that allows the subsequent lint step to access these results without invoking another agent.

### Lint Step Consumption

In [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go), the lint step first checks for the presence of combined results:

```go
if sctx.Shared.HousekeepingLintAvailable() {
    // Use stored lint findings; skip agent call
    return useStashedFindings()
}

```

If the combined pass succeeded, the lint step consumes the stored findings and reports them immediately. If the combined output is missing or unparsable—detected via `if result.Output == nil { … }`—the lint step falls back to its own independent agent invocation, preserving correctness guarantees.

## Verification and Performance Impact

This optimization is rigorously verified in [`internal/pipeline/steps/housekeeping_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/housekeeping_test.go). The test at lines 336-340 asserts that only **one** agent invocation occurs when both duties are combined:

```go
t.Fatalf("document+lint cost %d agent invocations, want 1 …")

```

According to the `kunchenguid/no-mistakes` source code, this approach delivers concrete performance benefits:

- **Single cold agent invocation**: The pipeline pays for one agent startup rather than two, eliminating redundant initialization overhead.
- **Reduced latency**: The lint step skips its LLM round-trip when `combinedLint` is true, streamlining pipeline execution.
- **Lower resource usage**: Fewer LLM calls translate directly to lower compute expenses and reduced token consumption.
- **Graceful degradation**: The fallback mechanism ensures that parsing failures or edge cases never compromise linting correctness.

## Summary

- The combined document and lint housekeeping pass triggers automatically when `sctx.Config.Commands.Lint` is empty, requiring no manual configuration.
- The document step in [`internal/pipeline/steps/document.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/document.go) builds a merged prompt and stashes lint findings using `sctx.Shared.SetHousekeepingLint`.
- The lint step in [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go) retrieves stashed results via `HousekeepingLintAvailable()` to avoid duplicate agent calls.
- The `splitHousekeepingFindings` helper categorizes findings by their `category` field to separate documentation and lint concerns.
- A robust fallback mechanism ensures the lint step runs independently if the combined pass fails or produces invalid output.
- Tests in [`housekeeping_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/housekeeping_test.go) verify that the optimization reduces agent invocations from two to one.

## Frequently Asked Questions

### What triggers the combined document and lint housekeeping pass?

The pass activates automatically when the repository configuration lacks a deterministic lint command. Specifically, when `sctx.Config.Commands.Lint == ""` evaluates to true in [`internal/pipeline/steps/document.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/document.go), the system sets `combinedLint` to true and merges the lint duty into the document step.

### How does the lint step handle failures in the combined pass?

The lint step implements a defensive fallback strategy. If the combined output is missing, indicated by `result.Output == nil`, or if the stashed findings are unavailable, the lint step proceeds with its own independent agent invocation. This ensures that linting always occurs even when the combined pass encounters errors or produces unparsable results.

### What files handle the combined housekeeping optimization?

The optimization spans four key files: [`internal/pipeline/steps/document.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/document.go) implements the combined prompt and result stashing; [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go) consumes the stashed findings or falls back to independent execution; [`internal/pipeline/shared.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/shared.go) defines the context methods like `SetHousekeepingLint` and `HousekeepingLintAvailable` for inter-step communication; and [`internal/pipeline/steps/housekeeping_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/housekeeping_test.go) verifies the single-invocation behavior.

### Is configuration required to enable this optimization?

No additional configuration is required. The system detects empty lint commands automatically and enables the combined pass transparently. Users simply omit the lint command from their configuration to trigger the optimization, and the pipeline handles the rest through the `combinedLint` detection logic in the document step.