# How to Handle Recurring Failure Patterns Using `known-issues.md` in Google Skills

> Learn to manage recurring failure patterns in Google Skills using the known-issues.md file. Find root-cause analysis and quick fixes for common troubleshooting scenarios.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-09-04

---

**The [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) file in the Google Skills repository serves as a centralized index of numbered recurring failure patterns (BKIs), providing root-cause analysis and specific remediation steps to resolve common Agent Platform troubleshooting scenarios without deep source code investigation.**

The Google Skills repository maintains a structured troubleshooting framework under `skills/cloud/agent-platform-troubleshooting/` where repeatable failure modes are systematically cataloged. The [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) reference file acts as the definitive index for these patterns, enabling developers to map symptoms—such as permission errors or VPC Service Control failures—to documented work-arounds. Mastering this workflow allows teams to resolve integration issues efficiently and contribute new patterns to the shared knowledge base.

## Locating the Known Issues Reference File

The primary index resides at [`skills/cloud/agent-platform-troubleshooting/references/known-issues.md`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/known-issues.md). This file is part of the Agent Platform Troubleshooting skill collection and functions as a lightweight lookup table that connects symptoms to solutions. It is designed to be referenced alongside companion files such as [`field-manual.md`](https://github.com/google/skills/blob/main/field-manual.md) and [`agent-gateway.md`](https://github.com/google/skills/blob/main/agent-gateway.md), which provide contextual implementation details for specific BKI entries.

## Understanding the BKI Numbering Convention

Each entry in the index follows a **BKI (Known Issue)** numbering format (e.g., **BKI 13**, **BKI 21**, **BKI 18**). These identifiers are cross-referenced throughout the troubleshooting documentation using section symbols (e.g., `§13`, `§21`, `§18`), creating a linked ecosystem of failure patterns and their resolutions. When you encounter a recurring error, the goal is to match your symptom to the corresponding BKI number, then follow the referenced section to access the full remediation protocol.

## The Six-Step Workflow for Resolving Recurring Failures

### 1. Identify the Failure Symptom

Begin by capturing the exact error message, log output, or behavioral symptom. Common patterns include "Permission denied" errors, VPC Service Control authorization failures, or Cloud Run integration timeouts. Precise symptom identification is critical for matching against the BKI index.

### 2. Search the BKI Index

Open [`skills/cloud/agent-platform-troubleshooting/references/known-issues.md`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/known-issues.md) and scan for entries whose descriptions align with your observed symptom. Each BKI entry contains a concise summary of the failure pattern, allowing you to quickly locate the relevant numbered section.

### 3. Analyze the Root Cause

Navigate to the specific BKI section (referenced via `§[number]`). This section provides detailed analysis of the root cause, including prerequisite conditions that trigger the failure and architectural context explaining why the error occurs in the Agent Platform environment.

### 4. Apply the Prescribed Work-Around

Every BKI entry concludes with a **Work-Around** or **Remediation** block containing exact steps to resolve the issue. These instructions may include adjusting IAM policies, configuring VPC Service Controls, updating Cloud Run service settings, or modifying agent gateway configurations.

### 5. Validate the Resolution

Re-execute the operation that originally generated the failure. If the issue persists, re-examine the BKI entry for additional prerequisite conditions or consult cross-referenced files like [`field-manual.md`](https://github.com/google/skills/blob/main/field-manual.md) for alternative remediation paths.

### 6. Document New Patterns

If you encounter a recurring failure not currently indexed, add a new BKI entry to [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) following the established format. This ensures future developers can resolve the same pattern without rediscovering the solution, maintaining the knowledge base for the broader Skills ecosystem.

## Automating BKI Lookup from the Command Line

You can programmatically locate relevant BKI entries by searching the repository for error strings or parsing the known-issues file directly.

Use `grep` to identify potential matches across the codebase:

```bash

# Search for error patterns across the troubleshooting references

grep -R "Permission denied" skills/cloud/agent-platform-troubleshooting/

# Open known-issues.md at a specific BKI section (e.g., BKI 13)

less +/BKI\ 13 skills/cloud/agent-platform-troubleshooting/references/known-issues.md

```

For automated lookup within Python scripts:

```python
import re
import pathlib

def find_bki_by_symptom(error_msg: str) -> str:
    """Return the BKI number matching the supplied error message."""
    known_issues_path = pathlib.Path(
        "skills/cloud/agent-platform-troubleshooting/references/known-issues.md"
    )
    known_issues = known_issues_path.read_text()
    
    for line in known_issues.splitlines():
        if error_msg.lower() in line.lower():
            match = re.search(r"BKI\s+(\d+)", line)
            if match:
                return f"BKI {match.group(1)}"
    return "No matching BKI found"

# Example usage for integration permission issues

print(find_bki_by_symptom("integration permission issue"))

```

## Cross-Referencing Supporting Documentation

The [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) file does not operate in isolation. The ecosystem of troubleshooting references includes:

- **[`field-manual.md`](https://github.com/google/skills/blob/main/field-manual.md)** ([`skills/cloud/agent-platform-troubleshooting/references/field-manual.md`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/field-manual.md)): Provides contextual guidance on when to consult the known-issues index and contains direct cross-references to specific BKI sections such as `§13` and `§21` for field-level troubleshooting procedures.

- **[`agent-gateway.md`](https://github.com/google/skills/blob/main/agent-gateway.md)** ([`skills/cloud/agent-platform-troubleshooting/references/agent-gateway.md`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/agent-gateway.md)): Contains concrete implementation examples for VPC Service Controls and authorization issues, specifically referencing **BKI 18** for agent gateway configurations.

- **[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)** ([`skills/cloud/agent-platform-troubleshooting/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/SKILL.md)): Offers a high-level overview of the troubleshooting skill architecture, highlighting the role of [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) within the broader Agent Platform support strategy.

## Summary

- The **[`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md)** file at [`skills/cloud/agent-platform-troubleshooting/references/known-issues.md`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/known-issues.md) provides a numbered index (BKI) of recurring failure patterns for the Google Skills Agent Platform.
- Each **BKI entry** includes symptom descriptions, root-cause analysis, and specific remediation steps to resolve issues without code-level debugging.
- The workflow follows six stages: **symptom identification**, **index search**, **root-cause analysis**, **work-around application**, **validation**, and **documentation** of new patterns.
- **Cross-references** in [`field-manual.md`](https://github.com/google/skills/blob/main/field-manual.md) and [`agent-gateway.md`](https://github.com/google/skills/blob/main/agent-gateway.md) use BKI numbers (e.g., §13, §18) to link specific operational contexts to known solutions.
- Command-line tools like **`grep`** and Python scripts can automate the lookup of BKI entries based on error message content.

## Frequently Asked Questions

### What does BKI stand for in the known-issues.md file?

**BKI** stands for **Known Issue** and serves as the primary numbering system for cataloging recurring failure patterns in the Google Skills repository. Each BKI number (e.g., BKI 13, BKI 21) uniquely identifies a specific failure mode, its root cause, and the prescribed remediation steps, enabling consistent cross-referencing across [`field-manual.md`](https://github.com/google/skills/blob/main/field-manual.md) and [`agent-gateway.md`](https://github.com/google/skills/blob/main/agent-gateway.md).

### How do I add a new recurring failure pattern to the index?

First, verify the pattern does not already exist by searching [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) for matching symptoms. If the pattern is new, append a new BKI entry following the existing format: assign the next sequential BKI number, describe the symptom and root cause, and document the specific work-around or remediation steps. Ensure you reference this new BKI in any affected operational files to maintain the cross-linked documentation structure.

### Where can I find examples of BKI entry structures for VPC Service Control issues?

Concrete examples of VPC Service Control-related BKI entries, including **BKI 18**, are documented in [`skills/cloud/agent-platform-troubleshooting/references/agent-gateway.md`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/agent-gateway.md). This file demonstrates how VPC-SC authorization failures are mapped to specific BKI numbers and provides implementation context for the remediation steps outlined in the main [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) file.

### What is the relationship between known-issues.md and field-manual.md?

The [`field-manual.md`](https://github.com/google/skills/blob/main/field-manual.md) file provides operational context and procedural guidance for field troubleshooting, while [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) serves as the technical index of failure patterns. The field manual references specific BKI sections (e.g., `§13`, `§21`) to direct users to the detailed symptom analysis and work-arounds stored in the known-issues file, creating a layered documentation approach that separates procedural workflow from technical root-cause analysis.