How the Combined Document and Lint Housekeeping Pass Optimizes Pipeline Execution

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, the implementation checks this condition:

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:

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 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, the lint step first checks for the presence of combined results:

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. The test at lines 336-340 asserts that only one agent invocation occurs when both duties are combined:

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 builds a merged prompt and stashes lint findings using sctx.Shared.SetHousekeepingLint.
• The lint step in 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 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, 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 implements the combined prompt and result stashing; internal/pipeline/steps/lint.go consumes the stashed findings or falls back to independent execution; internal/pipeline/shared.go defines the context methods like SetHousekeepingLint and HousekeepingLintAvailable for inter-step communication; and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}