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

> Learn about the combined document and lint housekeeping pass in no-mistakes. This feature merges docs and lint checks into one LLM agent, reducing latency and cost.

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

---

**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."*

```go
// 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.

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/housekeeping_test.go) and [`journey_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.