What Is the Combined Document and Lint Housekeeping Pass in no-mistakes?

The combined document and lint housekeeping pass in no-mistakes merges documentation updates and lint checks into a single LLM agent invocation, eliminating a redundant cold-start and reducing pipeline latency and cost.

The no-mistakes repository (kunchenguid/no-mistakes) implements a specialized pipeline optimization that consolidates two distinct quality gates into one efficient operation. When configured with an empty commands.lint setting, the system triggers this combined pass to avoid the performance penalty of initializing the LLM-powered agent twice. This architectural decision significantly reduces both execution time and operational costs for automated code review workflows.

Why Combine Document and Lint Steps?

In the standard pipeline flow, the document step writes documentation and then hands control to the lint step, which would normally trigger a second agent run. This creates two separate cold-starts of the LLM, introducing unnecessary latency and doubling the initialization overhead.

When the repository configuration leaves commands.lint empty, the document step automatically assumes responsibility for both operations. It appends a hidden lint section (housekeepingLintSection) to its own prompt and records the lint findings in a shared struct (HousekeepingLintResult). The subsequent lint step detects this pre-computed result and skips its own agent invocation entirely, creating a seamless single-pass workflow.

How the Housekeeping Pass Works

The implementation spans multiple files in internal/pipeline/steps/ and relies on careful coordination between the document and lint stages.

Prompt Construction in document.go

The document step builds a specialized prompt by injecting the housekeepingLintSection constant. This section contains a raw JSON schema (housekeepingFindingsSchema) that extends the regular findingsSchema with a top-level Category field. The prompt's purpose is explicitly set to "housekeeping", and its intro directs the agent to "Perform the combined documentation and lint housekeeping pass for this change."

// In internal/pipeline/steps/document.go
const housekeepingLintSection = `
{
  "purpose": "housekeeping",
  "section": "lint",
  "schema": ` + string(housekeepingFindingsSchema) + `
}
`

Result Handling and Storage

After the agent returns its response, the document step attempts to parse the JSON output into a types.Findings struct. Successful parsing extracts the lintFindings, which are then stored in the shared pipeline context via sctx.Shared.SetHousekeepingLint(). This storage mechanism makes the results available to downstream steps without requiring additional LLM calls.

// After the agent finishes:
var findings types.Findings
if err := json.Unmarshal(agentResult.Output, &findings); err != nil {
    // unparsable → request human approval
    return documentApprovalOutcome("combined housekeeping lint result unreadable"), nil
}
sctx.Shared.SetHousekeepingLint(pipeline.HousekeepingLintResult{
    FindingsJSON: agentResult.Output,
    Summary:      fmt.Sprintf("%d unresolved items", len(findings.Items)),
})

Lint Step Detection and Reuse

The lint step (internal/pipeline/steps/lint.go) begins by checking the shared context for existing housekeeping results using sctx.Shared.HousekeepingLint(). When this returns a non-nil result, the step logs the discovery and immediately returns the cached findings rather than invoking the agent.

// In internal/pipeline/steps/lint.go
if sctx.Shared.HousekeepingLint() != nil {
    // Re‑use the findings from the document step
    lintFindings := sctx.Shared.HousekeepingLint()
    sctx.Log(fmt.Sprintf(
        "housekeeping lint result recorded for the lint step: %d unresolved items",
        len(lintFindings.Findings.Items),
    ))
    return nil
}
// …otherwise run the normal lint agent

Error Handling and Safety Mechanisms

If the combined result cannot be parsed as valid JSON, the system implements a fail-safe mechanism. The document step forces an approval gate (documentApprovalOutcome) that requires human intervention before the pipeline can proceed. This ensures that malformed or unexpected agent outputs do not silently bypass quality checks or corrupt the pipeline state.

Testing and Verification

The no-mistakes codebase includes comprehensive test coverage to guarantee the efficiency of this optimization. The file internal/pipeline/steps/housekeeping_test.go contains unit tests that assert only one agent invocation occurs during a combined pass. Additionally, internal/e2e/journey_test.go validates the end-to-end flow, confirming that the lint prompt is completely omitted when the housekeeping results are present in the shared context.

Summary

• The combined document and lint housekeeping pass merges two pipeline stages into a single LLM invocation when commands.lint is empty.
• The document step in internal/pipeline/steps/document.go constructs a special prompt with the housekeepingLintSection and stores results via SetHousekeepingLint().
• The lint step detects cached results through sctx.Shared.HousekeepingLint() and skips redundant agent initialization.
• Parse failures trigger a mandatory documentApprovalOutcome gate for human review.
• Test coverage in housekeeping_test.go and journey_test.go ensures the optimization maintains correctness while improving performance.

Frequently Asked Questions

What triggers the combined housekeeping pass in no-mistakes?

The combined pass activates automatically when the repository configuration contains an empty commands.lint field. In this state, the document step recognizes it must handle both documentation generation and lint checking, appending the housekeepingLintSection to its prompt and storing results for the lint step to retrieve.

How does the lint step know to skip its agent invocation?

The lint step checks the shared pipeline context using sctx.Shared.HousekeepingLint() at the start of its execution. If this method returns a non-nil HousekeepingLintResult struct, the step logs the cached findings and returns immediately, avoiding the overhead of a second LLM cold-start.

What happens if the combined housekeeping result is malformed?

If the document step cannot parse the agent's JSON response into the expected types.Findings struct, it triggers a safety mechanism by returning documentApprovalOutcome("combined housekeeping lint result unreadable"). This forces a human approval gate, preventing the pipeline from proceeding with potentially corrupted or incomplete lint data.

Where is the housekeeping lint data stored between pipeline steps?

The data persists in the shared pipeline context defined in internal/pipeline/shared.go. The document step stores the results using sctx.Shared.SetHousekeepingLint(), and the lint step retrieves them using the corresponding getter method, enabling inter-step communication without additional file I/O or agent calls.

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