# AI Guidelines — magento-shippingfields

**Scope:** `modules/magento-shippingfields`
Path rule: Use repository-relative paths only. Absolute or machine-specific filesystem paths are prohibited.
**Mode:** Audit + Documentation Authoring
**Code changes:** **PROHIBITED** (read-only for any non-doc files)
**Documentation changes:** **ALLOWED** (create/update docs only)
**Mermaid standard authority:** `/docs/MERMAID_DIAGRAM_STANDARDS.md`
**Last verified:** 2026-02-26

---

## 0) Purpose

This module currently lacks (or has incomplete) documentation. Your job is to:

1. Discover what exists (evidence-based).
2. Produce a complete, consistent documentation set for this module.
3. Make the module understandable to developers and AI tools (e.g., GitHub Copilot) without inventing architecture.

You are **not** designing improvements. You are documenting observed reality.

---

## 1) Hard Rules

### 1.1 Do not change code

You must NOT modify any non-documentation file, including but not limited to:

* application/source code
* configuration used by runtime
* build scripts
* dependency manifests/lockfiles
* infrastructure definitions

### 1.2 Documentation-only edits allowed

You may:

* create missing documentation files
* update existing documentation files for clarity/completeness
* add diagrams (Mermaid) inside documentation files

### 1.3 Mermaid compliance is mandatory

Before writing any Mermaid diagram, you must read and comply with:

`/docs/MERMAID_DIAGRAM_STANDARDS.md`

Rules:

* Only use diagram types/styles allowed by the standard.
* Follow naming and direction conventions.
* If the standard is missing or unclear: **stop and ask**.

### 1.4 Evidence-first; no invention

* All “facts” must be backed by file evidence.
* Evidence must use repository-relative paths.
* If something cannot be evidenced, you must write:

`UNKNOWN — Requires Clarification`

Do not guess.

### 1.5 One-module focus

Operate only within `modules/magento-shippingfields`.
If the user request appears to span multiple modules, stop and ask which module is in scope.

---

## 2) Path & Reference Discipline

To ensure portability across machines, CI environments, and AI tooling, all file references must follow these rules.

### 2.1 Repository-Relative Paths Only

All file references must use repository-relative paths.

Correct:

* `/modules/magento-shippingfields/src/Controller/FooController.php`
* `/modules/magento-shippingfields/docs/architecture.md`
* `/docs/MERMAID_DIAGRAM_STANDARDS.md`

Prohibited:

* `C:\Users\dev\project\modules\...`
* `/Users/john/dev/project/...`
* `../../relative/from/current/file`

Absolute or machine-specific filesystem paths are not allowed.

---

### 2.2 Forward Slash Convention

Always use forward slashes `/` regardless of operating system.

Do not use:

* `\` (Windows-style paths)

---

### 2.3 Full Explicit Paths (No Ambiguity)

Do not reference files ambiguously.

Avoid:

* “the config file”
* “the controller”
* “the main service”

Instead use:

* `/modules/magento-shippingfields/config/web.php`
* `/modules/magento-shippingfields/src/Service/InvoiceService.php`

---

### 2.4 Evidence Section Format

When documenting evidence, include a clearly labeled section:

## Evidence

* /modules/magento-shippingfields/composer.json
* /modules/magento-shippingfields/src/Controller/ActivityController.php

Do not include local path prefixes or IDE-generated paths.

---

### 2.5 Cross-Module References

If referencing another module:

* Use full repository-relative path.
* Do not assume shared runtime or ownership unless documented.

Example:

* `/modules/billing/docs/API.md`

---

## 3) Mandatory Read Order

1. `modules/magento-shippingfields/README.md` (if present)
2. `modules/magento-shippingfields/AI_GUIDELINES.md` (this file)
3. `modules/magento-shippingfields/docs/*` (existing)
4. Repository governance docs (if present):

   * `/docs/AI_GUIDELINES.md`
   * `/docs/API.md`
   * `/docs/WORKFLOW.md`
   * `/docs/OBSERVABILITY.md`
   * `/docs/MERMAID_DIAGRAM_STANDARDS.md` (must-read for diagrams)

If any conflicts exist between module docs and repo docs:

* document the conflict (with evidence)
* do not resolve unilaterally
* ask one targeted question

---

## 4) Required Documentation Set (Create If Missing)

You must ensure these files exist inside this module:

### Root

* `modules/magento-shippingfields/README.md`

### Docs

* `modules/magento-shippingfields/docs/architecture.md`
* `modules/magento-shippingfields/docs/BOUNDARIES.md`
* `modules/magento-shippingfields/docs/DATA_OWNERSHIP.md`
* `modules/magento-shippingfields/docs/INTEGRATIONS.md`
* `modules/magento-shippingfields/docs/API.md`
* `modules/magento-shippingfields/docs/OBSERVABILITY.md`
* `modules/magento-shippingfields/docs/WORKFLOW.md`
* `modules/magento-shippingfields/docs/GDPR.md`

### ADRs

* `modules/magento-shippingfields/docs/adr/ADR-000-discovery-baseline.md`

Notes:

* Do **not** create a `docs/mermaid/` folder.
* Mermaid diagrams must live **inside** the relevant docs (architecture/API/integrations/boundaries), not in a separate “flows” file.

---

## 5) Diagram Placement Rules (No Separate Flows File)

When diagrams are needed, embed them as Mermaid blocks inside the most relevant document:

* `docs/architecture.md`

  * System context diagram
  * Main request/job flow diagram
* `docs/INTEGRATIONS.md`

  * Integration flow(s) per system boundary
* `docs/API.md`

  * Request lifecycle / sequence diagram for key endpoints (if evidenced)
* `docs/BOUNDARIES.md`

  * Boundary map (if standards permit the chosen diagram type)

If a flow is partially unknown:

* include only evidenced nodes/edges
* annotate unknown edges using Mermaid comments per standards, e.g.:

  * `%% UNKNOWN — Requires Clarification`

---

## 6) Required Content Discipline (What Each Doc Must Contain)

Every created/updated doc must include:

### 6.1 Confirmed Facts

* Bullet list of evidenced facts.

### 6.2 Evidence

* Repository-relative file path references used to justify facts.

### 6.3 Unknowns

* Explicit list using the exact token:

  * `UNKNOWN — Requires Clarification`

This ensures unknowns are searchable across modules.

---

## 7) API Governance (Module-Level)

In `docs/API.md`, you must include and preserve this contract language:

> All externally consumed API behaviour must be defined in this document. Undocumented behaviour is undefined and unsupported.

If you cannot determine whether an API is externally consumed:

* mark it `UNKNOWN — Requires Clarification`
* do not assume public/internal

---

## 8) Observability Governance (Module-Level)

In `docs/OBSERVABILITY.md`, document what exists (evidence-based) for:

* logging
* metrics
* tracing
* correlation IDs

If cross-system calls exist, explicitly document:

* whether correlation IDs are propagated (or `UNKNOWN — Requires Clarification`)
* failure classification by ownership boundary (or `UNKNOWN — Requires Clarification`)

Do not add new instrumentation (code changes prohibited).

---

## 9) Gap Classification (Required)

As you audit, record gaps using one of:

* DOCUMENTATION GAP
* OWNERSHIP GAP
* BOUNDARY GAP
* API CONTRACT GAP
* OBSERVABILITY GAP
* SECURITY CLARITY GAP
* CONFIGURATION GAP

Each gap must include:

* what is missing
* where you looked (repository-relative evidence paths)
* the minimum documentation addition required

---

## 10) Stop Conditions (Ask One Targeted Question)

Stop and ask if any of these block accurate documentation:

* primary entrypoint/runtime cannot be identified
* data store ownership/system-of-record is ambiguous
* multiple APIs exist and public vs internal is unclear
* Mermaid standards doc is missing or incompatible
* multiple modules appear to be in scope

Ask one targeted question at a time.

---

## 11) Definition of Done

This documentation task is complete only when:

* All required files in section 4 exist
* Each doc includes: Confirmed Facts + Evidence + Unknowns
* Mermaid diagrams are standards-compliant and embedded in relevant docs
* Unknowns use the exact token: `UNKNOWN — Requires Clarification`
* No non-doc files were modified
* ADR-000 exists and lists follow-up clarifications
* All file references follow the Path & Reference Discipline


## 12) Implementation Mode (Explicit Only)

Code changes within this module are prohibited by default.

To allow code changes, the user must explicitly state:

> "Enable Implementation Mode for this module."

When Implementation Mode is enabled:

1. A written plan is required before any code modification.

2. The plan must include:
   - Exact files within modules/magento-shippingfields to modify
   - Unified diffs
   - Risk assessment
   - Documentation impact (API, boundaries, ownership, observability)

3. Explicit approval is required before applying changes.

4. Changes must be limited strictly to the approved files.

5. Any scope expansion requires re-approval.

6. Cross-module changes are not allowed unless explicitly approved.

If Implementation Mode is not explicitly enabled, all code changes remain prohibited.