# Project Working Guide

<!--
Template instructions:
1. Copy this file to the root of the new project.
2. Rename the copy AGENTS.md.
3. Replace bracketed text and delete sections that do not apply.
4. Keep the instructions concise enough to guide routine work.
-->

## Purpose

This project [briefly describe what the project investigates, demonstrates,
or builds].

The primary goal is to [state the concrete technical or educational outcome].

This is [experimental demonstration / research / production] code. Favor
[clarity, flexibility, traceability, performance, or another priority].

## Audience and User Background

The intended audience is [engineers, scientists, students, maintainers, or
another group].

Assume the primary user has [beginner / intermediate / advanced] MATLAB
experience and [describe relevant domain knowledge].

Explain [topics that deserve explanation] without overexplaining [topics the
user already understands].

Delete this section when personal learning or communication context is not
useful to the project.

## MATLAB Problem-Solving Style

- Prefer array and matrix operations over scalar, element-by-element loops
  when the calculation is naturally array-oriented.
- Prefer logical indexing when a logical mask is sufficient. Use `find` only
  when numeric indices are needed.
- Before writing a loop, consider colon indexing, logical masks, implicit
  expansion, `reshape`, `sum`, `mean`, `any`, `all`, and related array tools.
- Retain loops when they clearly express a sequential, iterative, stateful, or
  moving-window algorithm.
- Preallocate outputs when a loop is appropriate.
- Make array dimensions and row-versus-column orientation explicit.
- Distinguish matrix operations (`*`, `/`, `\`, `'`) from element-wise
  operations (`.*`, `./`, `.^`) and nonconjugating transpose (`.'`).
- Prefer solving a system with `A\b` over explicitly forming `inv(A)*b`.
- When educational value matters, explain the relationship between a manual
  algorithm and the corresponding MATLAB function.

## Code Style

- Keep the main workflow readable from top to bottom.
- Put primary user configuration near the top of a script.
- Use local functions for validation, repetitive work, and details that would
  interrupt the main flow.
- Comment why a step is necessary; do not narrate obvious statements.
- Prefer descriptive names over explanatory comments.
- Avoid architecture or dependencies that do not provide proportional value.
- Preserve complete native error information unless shorter reporting is a
  stated requirement.
- [Add project-specific naming, formatting, or toolbox conventions.]

## Hardware and Safety

<!-- Delete this section when the project does not control hardware. -->

- Target hardware: [instrument, device, circuit, or system].
- Verify [voltage, current, power, frequency, loading, or other limits] before
  enabling an output.
- Keep outputs disabled until configuration and read-back checks pass.
- Leave hardware in a deliberate, documented state after success or failure.
- Do not change [safety-critical setting] without explicit user direction.

## Verification

After making a change:

1. Run [syntax check, unit test, MATLAB script, simulation, or other check].
2. Compare [computed, commanded, or measured values] with [expected values].
3. Report tests that could not be run and why.
4. Do not claim hardware verification unless the hardware was actually used.

## Reference Library

<!-- Delete this section when the project has no reference library. -->

Start with:

- `[path/to/reference-index.md]` for topic and page routing.
- `[path/to/methods-guide.md]` for distinctive algorithms or conventions.
- `[path/to/style-guide.md]` for detailed MATLAB preferences.

Before designing work in [relevant technical areas]:

1. Search the index for the relevant source sections.
2. Read only the pages needed for the current task, including important
   figures.
3. Consider both the instructional method and current MATLAB functions.
4. Verify release-sensitive APIs and hardware behavior against current
   authoritative documentation.
5. Preserve attribution when a source materially influences the solution.

Do not load an entire large reference library when selective retrieval is
sufficient.

## User-Directed Experimental Loop

<!-- Delete or adapt this section when the project has no executable or
measurable feedback loop. -->

Use this loop when the available environment and user authorization support
it:

1. Define the experiment or task, expected outcome, and applicable limits.
2. Expand the reference library when useful. Add or link only an authorized
   source; record attribution and reuse terms; index the relevant sections;
   and preserve distinctive methods in the appropriate guide.
3. Consult the project guidance, reference indexes, prior retrospectives, and
   only the source sections relevant to the task.
4. Develop or revise code within the bounded project folder.
5. Obtain explicit user approval before consequential hardware operations.
6. Execute through [MATLAB, Python, terminal, IDE, or another environment]
   and inspect program output and device read-back.
7. Independently observe the physical or computed result with [measurement
   instrument, visualization, simulation, or other evidence].
8. Compare the requested behavior, system read-back, and independent result.
9. Incorporate validated findings into the code, indexes, documentation, and
   project retrospective before beginning the next cycle.

Reference material supplies contextual retrieval, not permanent model
training. Access to applications, network instruments, and displays is
session-specific and user-authorized. Reading this file does not itself grant
computer-control or hardware access.

## Collaboration Preferences

<!-- Adapt or remove these rules for another user. -->

- Lead with the result and explain technical choices in plain language.
- Ask for clarification only when a missing choice would materially change
  the result.
- Respectfully flag possible project drift when peripheral tooling begins to
  displace the main objective.
- Distinguish technical problems from useful learning investigations and
  tooling friction that can safely be bypassed.
- [Add individual communication or learning preferences with permission.]

## File Handling

- Treat files currently saved on disk as the source of truth.
- Re-read a file immediately before modifying it.
- Preserve manual edits unless they conflict with the requested change.
- [Choose one revision policy:]
  - Modify the named file in place and rely on version control.
  - Never overwrite an existing revision; create the next `_TkN` revision.
- Do not delete earlier work unless explicitly requested.
- Report the exact files created or changed.

## Scope

Before adding architecture, dependencies, abstractions, or new hardware,
consider whether they improve the project’s stated goal.

Identify any material expansion of scope before implementing it.
