# Mandatory Skill Routing

Skills are mandatory procedures, not optional reference material.

Before performing any specialized operation, identify the applicable skill(s)
and read their `SKILL.md` before executing the operation.

Examples of specialized operations include:
- building;
- running tests;
- C/C++ semantic analysis;
- compiler-diagnostic analysis;
- debugging;
- code generation.

If an applicable skill exists:
- MUST use that skill.
- MUST NOT construct an alternative procedure from memory.
- MUST NOT silently substitute another tool or workflow.
- MUST follow the skill's preconditions before executing its commands.

If no applicable skill can be identified for an operation that requires one:
report this to the user and STOP before performing that operation.

# General Workflow

- **User Guidance:** Proactively communicate your plan and the reason for each
  step.
- **File Creation Pre-check:** Before creating any new file, you MUST first
  perform a thorough search for existing files that can be modified or
  extended. This is especially critical for tests; never create a new test file
  if one already exists for the component in question. Always add new tests to
  the existing test file.
- **Read Before Write/Edit:** **ALWAYS** read the entire file content
  immediately before writing or editing.
- **Problems on the way:** **ALWAYS** report to user if something is not working 
  as expected from Skills or AGENTS.md
- **Missing in environment:** **ALWAYS** report to user if something is missing
  in work environment

## Hard Stops

An unexpected command failure is terminal for the current turn. This includes a
non-zero exit status, a missing required tool or configuration, an unavailable
service, malformed required output, or a denied permission, unless the user
explicitly asked to investigate that failure.

On such a failure, immediately report the command or operation, its exit status
or failure condition, and the complete preserved failure output or its log
location. Then STOP. Do not retry, substitute a command, run further diagnosis,
kill a process, clean output, regenerate configuration, or edit code until the
user gives a new instruction.

For C/C++ edits, a language-server diagnostic error is also a hard stop before
any build. Use the applicable diagnostic skill to run diagnostics for every
modified C/C++ source or header file. Report all errors and warnings; do not
build while any error remains or when diagnostics cannot be run.

## Standard Edit/Fix Workflow

**IMPORTANT:** This workflow takes precedence over all other coding
instructions. Read and follow everything strictly without skipping steps
whenever code editing is involved. Any skipping requires a proactive message to
the user about the reason to skip.

1. **Comprehensive Code and Task Understanding (MANDATORY FIRST STEP):** Before
   writing or modifying any code, you MUST perform the following analysis to
   ensure comprehensive understanding of the relevant code and the task. This
   is a non-negotiable prerequisite for all coding tasks.
   - **a. Identify the Core Files:** Locate the files that are most relevant to
     the user's request. All analysis starts from these files.
   - **b. Conduct a Full Audit:**
     - **IMPORTANT** For deeper understanding language server should be used if available.  
     - Read the full source of **EVERY** core file.
     - For each core file, summarize the control flow and ownership semantics.
       State the intended purpose of the core file.
   - **c. State Your Understanding:** After completing the audit, you should
     briefly state the core files you have reviewed, confirming your
     understanding of the data flow and component interactions before proposing
     a plan.
   - **d. Anti-Patterns to AVOID:**
     - **NEVER** assume the behavior of a function or class from its name or
       from usage in other files. **ALWAYS** read the source implementation.
     - **ALWAYS** check at least one call-site for a function or class to
       understand its usage. The context is as important as the implementation.
2. **Make Change:** After a comprehensive code and task understanding, apply the
   edit or write the file.
   - When making code edits, focus **ONLY** on code edits that directly solve
     the task prompted by the user.
   - After modifying C/C++ source or header files, run the applicable
     language-server diagnostics before proceeding to a build. Follow the
     **Hard Stops** section if diagnostics find an error or cannot run.
3. **Write/Update Tests:**
   - First, search for existing tests related to the modified code and update
     them as needed to reflect the changes.
   - If no relevant tests exist, write new unit tests or integration tests if
     it's reasonable and beneficial for the change made.
   - If tests are deemed not applicable for a specific change (e.g., a trivial
     comment update), explicitly state this and the reason why before moving to
     the next step.
4. **Build:** **ALWAYS** build relevant targets after making edits.
5. **Fix compile errors:** **ALWAYS** follow these steps to fix compile errors.
   - **ALWAYS** take the time to fully understand the problem before making any
     fixes.
   - **ALWAYS** read at least one new file for each compile error.
   - **ALWAYS** find, read, and understand **ALL** files related to each
     compile error. For example, if an error is related to a missing member of
     a class, find the file that defines the interface for the class, read the
     whole file, and then create a high-level summary of the file that outlines
     all core concepts. Come up with a plan to fix the error.
   - **ALWAYS** check the conversation history to see if this same error
     occurred earlier, and analyze previous solutions to see why they didn't
     work.
   - **NEVER** make speculative fixes. You should be confident before applying
     any fix that it will work. If you are not confident, read more files.
6. **Test:** **ALWAYS** run relevant tests after a successful build. If you
   cannot find any relevant test files, you may prompt the user to ask how this
   change should be tested.
7. **Fix test errors:**
   - **ALWAYS** take the time to fully understand the problem before making any
     fixes.
8. **Iterate:** Repeat building and testing using the above steps until all are
   successful.

# Chromium Directives

## Paths

- All files in Chromium's source can be read by substituting `chromium/src` or
  `//` for the current workspace (which can be determined by running
  `gclient root` and appending `/src` to the output).

## Building

- Do not attempt a build without first establishing the correct output
  directory and target. If you have not been given them, and you plan on doing
  a build, then stop and ask before starting on any other tasks.
- **ALWAYS** Ask user for build environment details
- Immediately before launching a Chromium build, use the applicable build
  skill's pre-launch procedure to verify the configured locations, environment
  variables, wrapper, output directory, and target.
- Check for an existing Chromium build before launching a new one. If one is
  running, report it and STOP. Never kill, restart, or replace a running build
  without the user's explicit permission.
- When reporting build status from a log, cite only output produced after the
  current build session was launched. Do not treat earlier log sessions as
  evidence about the current build.

## Testing

**ALWAYS** ask user on test running details

When using `tools/autotest.py`:
- Do not invoke `autoninja` beforehand because `autotest.py` automatically
  builds relevant targets.
- Build targets containing colons (`:`) are not valid inputs for
  `{RELEVANT_TEST_FILENAMES}`.

## Coding

- Stay on task: Do not address code health issues or TODOs in code unless it is
  required to achieve your given task.
- Add code comments sparingly: Focus on *why* something is done, not *what* is
  done.

# Knowledge Base (adapted from `agents/prompts/knowledge_base.md`)

You MUST NOT answer from your general knowledge alone. The Chromium codebase is
vast and specific. Before answering any query, consult the relevant docs and
source. Canonical documentation is in `docs/`, and Chromium-specific docs exist
throughout `docs/`.

Use this guide to decide which documents to consult:

## Core Programming Patterns

- **Communication between components/processes (e.g., browser-to-renderer):**
  Look for **Mojo IPC interfaces (`.mojom` files)** that define the protocol
  between components. Read the `.mojom` file to understand the data structures
  and methods.
- **Asynchronous operations or threading:** Look for usage of
  `base::TaskRunner` and `base::BindOnce`/`base::BindRepeating` for posting
  tasks to the correct sequence or thread.
- **Code inside `third_party/blink/renderer/`:**
  Blink has its own memory management and containers. **You MUST use container
  and string types from `third_party/blink/renderer/platform/wtf/`** (e.g.,
  `blink::Vector`, `blink::String`) and **Oilpan for GC** (`Member<>`,
  `WeakMember<>`, `Persistent<>`). **DO NOT** use STL containers or most `base/`
  equivalents inside Blink code.
- **Threading/Callbacks:**
  - Threading (`base::Thread`, `base::TaskRunner`, `base::PostTask`, sequences):
    consult `docs/threading_and_tasks.md`.
  - Callbacks (`base::OnceCallback`, `base::RepeatingCallback`, `base::Bind`):
    consult `docs/callback.md`.

## Adding a User Preference (Pref)
For prefs/settings (`pref`, `preference`, `setting`, `PrefService`): consult
`components/prefs/README.md`.

## Adding a New UMA Metric

- For UMA histograms/metrics: consult `docs/metrics/uma/README.md`.

## Modifying BUILD.gn files

- For style/best practices: consult `docs/imported/gn/style_guide.md`.

## Adding a New UKM Metric

- For UKM metrics: consult `tools/metrics/ukm/README.md`.

## Debugging

- **Header file not found:**
  1. Verify `deps` in the `BUILD.gn` of the failing target.
  2. Verify the `#include` path.
  3. (Infer from Target System Skill, if presented) Regenerate build files: `gn gen <out_dir>`.
  4. (Infer from Target System Skill, if presented) Confirm GN sees the dep: `gn desc <out_dir> //failing:target deps`.
  5. (Infer from Target System Skill, if presented) Check for issues: `gn check <out_dir> //failing:target`.
- **Linker error (undefined symbol):** check the target providing the symbol is
  in `deps` (`gn desc`), and that `is_component_build` is set as expected in
  `args.gn`.
- **Visibility error:** add the depending target to `visibility` in the
  dependency's `BUILD.gn`.
- **General runtime debugging:** consult `docs/debugging.md`.

# Landmines

These rules exist because certain commands are too slow or crash/hang agents on
Chromium's large source tree, or because they are destructive.

- Read files one at a time with the `read` tool. Do not batch-read or echo out
  the entire contents of many large files in one turn.
- Any time you want to use `grep -r`, `grep -R`, or `git grep`, use `rg`
  instead.
- Any time you want to use `find`, use `fdfind` instead.
- If running `rg` or `fdfind` fails because the executables are missing, tell
  the user to install them with the following command, and then stop:
  ```
  sudo apt-get install ripgrep fd-find
  ```
- Never directly install software with `brew` or `apt-get` - instead suggest
  the required installation to the user with the full command line, and then
  stop.
- Never amend git commits (`git commit --amend`). Always create new ones.
- Do not use recursive directory-wide searches that hang on this tree; prefer
  targeted `rg`/`fdfind` queries.