how-to-guide

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

September 4, 2026 google/skills ↗

The 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 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. 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 and 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 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 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 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:


# 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:

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 file does not operate in isolation. The ecosystem of troubleshooting references includes:

Summary

  • The known-issues.md file at 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 and 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 and 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 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. 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 file.

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

The field-manual.md file provides operational context and procedural guidance for field troubleshooting, while 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.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →