From fd5e2c1685fad78ad4cc6db2b7185c54638b5431 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jose=20Villase=C3=B1or=20Montfort?= <195970+montfort@users.noreply.github.com> Date: Mon, 23 Mar 2026 17:43:30 -0600 Subject: [PATCH] fix: formalize tags and related conventions in framework docs (#25) Add explicit conventions for frontmatter tags and related fields to resolve ambiguity that caused inconsistent agent behavior. Tags: - kebab-case keywords, 3-8 per document - Describe topic, technology, component, or concern Related: - DevTrail document filenames only (with .md extension) - Include path from .devtrail/ for documents in subdirectories - Filename alone for same-directory or well-known documents - Explicitly prohibit task IDs, issue numbers, and URLs Updated files: - DOCUMENTATION-POLICY.md (EN + ES) - AGENT-RULES.md (EN + ES) - DEVTRAIL.md (unified rules) Co-Authored-By: Claude Opus 4.6 (1M context) --- dist/.devtrail/00-governance/AGENT-RULES.md | 15 ++++++ .../00-governance/DOCUMENTATION-POLICY.md | 46 ++++++++++++++++++- .../00-governance/i18n/es/AGENT-RULES.md | 15 ++++++ .../i18n/es/DOCUMENTATION-POLICY.md | 46 ++++++++++++++++++- dist/DEVTRAIL.md | 16 +++++++ 5 files changed, 134 insertions(+), 4 deletions(-) diff --git a/dist/.devtrail/00-governance/AGENT-RULES.md b/dist/.devtrail/00-governance/AGENT-RULES.md index 134ee8b..d4b09d4 100644 --- a/dist/.devtrail/00-governance/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/AGENT-RULES.md @@ -125,6 +125,21 @@ Before creating a document, load the corresponding template: | INC | `.devtrail/05-operations/incidents/` | | TDE | `.devtrail/06-evolution/technical-debt/` | +### Tags and Related + +When populating the `tags` and `related` fields in frontmatter: + +**Tags:** +- Use kebab-case keywords: `sqlite`, `api-design`, `gnome-integration` +- 3 to 8 tags per document describing topic, technology, or component +- Tags enable search and categorization in `devtrail explore` + +**Related:** +- Reference other **DevTrail documents only** — use the document filename with `.md` extension +- If the document is in a subdirectory within `.devtrail/`, include the relative path: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` +- If the document is in the same directory, the filename alone is sufficient +- **Do not** put task IDs (T001, US3), issue numbers, or external URLs in `related` — put those in the document body instead + --- ## 6. Communication with Humans diff --git a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md index cd2892c..f73b24a 100644 --- a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md @@ -70,11 +70,53 @@ related: | Field | Description | |-------|-------------| | `updated` | Last update date | -| `tags` | Tags for categorization | -| `related` | References to related documents | +| `tags` | Tags for categorization (see conventions below) | +| `related` | References to related documents (see conventions below) | | `supersedes` | ID of the document this one replaces | | `superseded_by` | ID of the document that replaces this one | +### Tags Convention + +Tags are **free-form keywords** used for categorization and search. They help discover related documents across the project. + +**Format rules:** +- Use **kebab-case** (lowercase, hyphens): `gnome-integration`, `sqlite`, `api-design` +- One concept per tag — avoid compound tags like `auth-and-security` +- Recommended range: **3 to 8 tags** per document +- Tags should describe the **topic**, **technology**, **component**, or **concern** of the document + +**Example:** +```yaml +tags: [sqlite, persistence, hexagonal-architecture, repository-pattern] +``` + +### Related Convention + +Related references link documents to other **DevTrail documents** within the same project. They enable cross-navigation in tools like `devtrail explore`. + +**Format rules:** +- Use the **document filename** (with `.md` extension): `AILOG-2026-02-03-001-implement-sync-item.md` +- For governance or non-typed documents, use the filename as-is: `AGENT-RULES.md`, `DOCUMENTATION-POLICY.md` +- Paths are resolved relative to `.devtrail/` — if the document is in a subdirectory, include the path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md` +- When the file is in the same directory as the referencing document, the filename alone is sufficient +- **Do not use** external task IDs (`T001`, `US3`), issue numbers, or URLs — those belong in the document body, not in frontmatter +- **Do not use** partial IDs without description (prefer `AILOG-2026-02-03-001-implement-sync-item.md` over `AILOG-2026-02-03-001`) + +**Examples:** +```yaml +# Same directory or well-known location — filename is enough +related: + - AIDEC-2026-02-02-001-sqlite-bundled-vs-system.md + - AGENT-RULES.md + +# Documents in specific subdirectories — include path from .devtrail/ +related: + - 07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md + - 02-design/decisions/ADR-2026-01-15-001-use-hexagonal-architecture.md +``` + +**Resolution:** The CLI resolves references by searching: (1) exact ID match, (2) filename match anywhere in `.devtrail/`, (3) path suffix match. Using the full filename provides the most reliable resolution. + --- ## 3. Document Statuses diff --git a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md index 4a8d0bd..31d698c 100644 --- a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md @@ -127,6 +127,21 @@ Antes de crear un documento, cargar la plantilla correspondiente: | INC | `.devtrail/05-operations/incidents/` | | TDE | `.devtrail/06-evolution/technical-debt/` | +### Tags y Related + +Al poblar los campos `tags` y `related` en el frontmatter: + +**Tags:** +- Usar palabras clave en kebab-case: `sqlite`, `api-design`, `gnome-integration` +- 3 a 8 tags por documento describiendo tema, tecnología o componente +- Los tags habilitan búsqueda y categorización en `devtrail explore` + +**Related:** +- Referenciar únicamente otros **documentos DevTrail** — usar el nombre de archivo con extensión `.md` +- Si el documento está en un subdirectorio dentro de `.devtrail/`, incluir la ruta relativa: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-archivo.md` +- Si el documento está en el mismo directorio, el nombre de archivo es suficiente +- **No** colocar IDs de tareas (T001, US3), números de issues ni URLs externas en `related` — esos van en el cuerpo del documento + --- ## 6. Comunicación con Humanos diff --git a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md index 9ae19b3..650ff7a 100644 --- a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md @@ -72,11 +72,53 @@ related: | Campo | Descripción | |-------|-------------| | `updated` | Fecha de última actualización | -| `tags` | Etiquetas para categorización | -| `related` | Referencias a documentos relacionados | +| `tags` | Etiquetas para categorización (ver convenciones abajo) | +| `related` | Referencias a documentos relacionados (ver convenciones abajo) | | `supersedes` | ID del documento que este reemplaza | | `superseded_by` | ID del documento que reemplaza a este | +### Convención de Tags + +Los tags son **palabras clave de formato libre** usadas para categorización y búsqueda. Ayudan a descubrir documentos relacionados en todo el proyecto. + +**Reglas de formato:** +- Usar **kebab-case** (minúsculas con guiones): `gnome-integration`, `sqlite`, `api-design` +- Un concepto por tag — evitar tags compuestos como `auth-y-seguridad` +- Rango recomendado: **3 a 8 tags** por documento +- Los tags deben describir el **tema**, **tecnología**, **componente** o **preocupación** del documento + +**Ejemplo:** +```yaml +tags: [sqlite, persistencia, hexagonal-architecture, repository-pattern] +``` + +### Convención de Related + +Las referencias relacionadas vinculan documentos con otros **documentos DevTrail** dentro del mismo proyecto. Permiten navegación cruzada en herramientas como `devtrail explore`. + +**Reglas de formato:** +- Usar el **nombre del archivo** del documento (con extensión `.md`): `AILOG-2026-02-03-001-implementar-sincronizacion.md` +- Para documentos de gobernanza u otros sin tipo, usar el nombre tal cual: `AGENT-RULES.md`, `DOCUMENTATION-POLICY.md` +- Las rutas se resuelven relativas a `.devtrail/` — si el documento está en un subdirectorio, incluir la ruta desde `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implementar-sincronizacion.md` +- Cuando el archivo está en el mismo directorio que el documento que lo referencia, el nombre de archivo es suficiente +- **No usar** IDs de tareas externas (`T001`, `US3`), números de issues ni URLs — esos pertenecen al cuerpo del documento, no al frontmatter +- **No usar** IDs parciales sin descripción (preferir `AILOG-2026-02-03-001-implementar-sincronizacion.md` sobre `AILOG-2026-02-03-001`) + +**Ejemplos:** +```yaml +# Mismo directorio o ubicación conocida — el nombre de archivo es suficiente +related: + - AIDEC-2026-02-02-001-sqlite-bundled-vs-system.md + - AGENT-RULES.md + +# Documentos en subdirectorios específicos — incluir ruta desde .devtrail/ +related: + - 07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implementar-sincronizacion.md + - 02-design/decisions/ADR-2026-01-15-001-usar-arquitectura-hexagonal.md +``` + +**Resolución:** El CLI resuelve referencias buscando: (1) coincidencia exacta de ID, (2) coincidencia de nombre de archivo en cualquier parte de `.devtrail/`, (3) coincidencia de sufijo de ruta. Usar el nombre de archivo completo proporciona la resolución más confiable. + --- ## 3. Estados de Documentos diff --git a/dist/DEVTRAIL.md b/dist/DEVTRAIL.md index d34888e..540743d 100644 --- a/dist/DEVTRAIL.md +++ b/dist/DEVTRAIL.md @@ -147,9 +147,25 @@ agent: your-agent-id-v1.0 confidence: high | medium | low review_required: true | false risk_level: low | medium | high | critical +tags: [oauth, authentication, api] +related: + - ADR-2025-01-20-001-use-jwt-tokens.md --- ``` +### Tags + +- Use **kebab-case** keywords: `sqlite`, `api-design`, `gnome-integration` +- 3 to 8 tags per document — describe topic, technology, or component +- Tags enable search and categorization in `devtrail explore` + +### Related + +- Reference other **DevTrail documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md` +- For documents in subdirectories, include path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` +- For documents in the same directory, filename alone is sufficient +- **Do not** use task IDs, issue numbers, or URLs — those go in the document body + --- ## 9. Autonomy Limits