context-authoring · git:20260627.06cb77d · 2026-06-27 · sha256 fbfd1e5657660ccf
context-authoring git:20260627.06cb77dA
Immutable. This exact content is served forever at /api/v1/blob/fbfd1e5657660ccf.
--- model_tier: inherit name: context-authoring description: "Use when filling knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive template walkthrough." domain: process workspaces: - agent-config-maintainer packs: - meta --- # context-authoring ## When to use Use this skill when: - A new project has been scaffolded and the `agents/settings/contexts/` files are still template stubs from `event4u/agent-config`. - The user asks "help me fill in the auth model context", "set up tenant boundaries", or similar knowledge-layer work. - A reviewer skill (`authz-review`, `data-flow-mapper`, `migration-safety`, `multi-tenant-boundary-review`, `secrets-and-config-review`) reports *"I cannot proceed — `agents/settings/contexts/<file>.md` is still a template"*. - After a significant architecture change that invalidates one of the five context files. Do NOT use when: - Writing a regular roadmap or feature doc — use `agent-docs-writing`. - Creating a generic context document that does not map to one of the five knowledge-layer templates — use `context-create`. - Filling in the engineering-memory YAML files (`domain-invariants.yml`, etc.) — use `/memory-add`. ## The five files | File | What it answers | Who reads it | |---|---|---| | `auth-model.md` | Roles, permission model, impersonation, known exceptions | `authz-review`, `judge-security-auditor`, `threat-modeling` | | `tenant-boundaries.md` | Tenancy type, scope propagation, known cross-tenant paths | `multi-tenant-boundary-review`, `blast-radius-analyzer`, `judge-security-auditor` | | `data-sensitivity.md` | Field classification, masking rules, log-safe types | `data-exposure-review`, `data-flow-mapper`, logging reviewers | | `deployment-order.md` | Migration strategy, feature flags, rollback plan | `migration-safety`, `judge-bug-hunter`, release reviewers | | `observability.md` | Error tracking, log channels, metrics, known alerts | deploy reviewers, `bug-analyzer`, incident mode | The templates ship in `.agent-src.uncondensed/templates/contexts/` and are copied into `agents/settings/contexts/` by the installer. ## Procedure: context-authoring ### Step 0: Inspect 1. List `agents/settings/contexts/` — which of the five files exist? Which still contain the `<!-- Template shipped by event4u/agent-config. -->` HTML comment? 2. Ask the user which file to work on. Use numbered options: ``` > 1. auth-model.md — roles, permissions, impersonation > 2. tenant-boundaries.md — tenancy type and scope propagation > 3. data-sensitivity.md — field classification and masking > 4. deployment-order.md — migrations, flags, rollback > 5. observability.md — errors, logs, metrics, alerts ``` 3. If multiple files are stubs, default to the order above — `auth-model` is the prerequisite for `tenant-boundaries`; both feed `data-sensitivity`. ### Step 1: Harvest evidence before asking For the chosen file, pull what the codebase already reveals before asking the user. Record the file:line citations — they become the authoritative source when the user is unsure. | File | Harvest from | |---|---| | `auth-model.md` | Policy classes, Gate definitions, permission seeders, role enums, `@can` directives, middleware | | `tenant-boundaries.md` | Base query scopes, connection-switching middleware, tenant-resolution service, global scopes, `.env` vars like `TENANT_*` | | `data-sensitivity.md` | ORM hidden-field config (Eloquent `$hidden` / `$casts`, Symfony `#[Ignore]`, Prisma `select` defaults, SQLAlchemy `__init__` filters), Sentry `beforeSend`, logging redaction helpers, API serialisers / resources, export commands | | `deployment-order.md` | `database/migrations/`, feature-flag config (Pennant / LaunchDarkly), deploy scripts, CI workflow, rollback runbooks in `docs/` | | `observability.md` | `config/logging.php`, Sentry init, dashboard links in READMEs, alert rules in Terraform/Grafana dashboards | Start the walkthrough by showing the harvested evidence — the user only has to confirm or correct, not invent from scratch. ### Step 2: Walk the template section by section 1. Open the template and treat **every HTML comment** as a question for the user. Do NOT fabricate answers to skip a section. 2. Present each section as: ``` **Section:** <heading> **Template asks:** <what the comment says> **Evidence I found:** <file:line references or "none"> **Proposed content:** <draft or "I need your input"> > 1. Accept the draft > 2. Edit — tell me what's wrong > 3. I don't know — mark as "TBD" with a follow-up task ``` 3. If the user picks "TBD", insert an HTML comment `<!-- TBD: <question> -->` at that spot — never a fabricated value. Reviewer skills key on the comment to warn about incomplete sections. ### Step 3: Preserve the file contract 1. Remove the top-of-file `<!-- Template shipped by ... -->` comment only after at least one section has been authored — an untouched file must stay recognisable as a stub. 2. Keep every heading the template ships with. Reviewer skills grep for exact section names (`## Known exceptions`, `## Known alerts`, etc.). 3. Do NOT add new top-level sections. The template surface is the contract — extend existing sections, file a proposal via `learning-to-rule-or-skill` to expand the template upstream. ### Step 4: Validate 1. Run `./scripts-run src/scripts/check_portability` — project-specific content is expected here, but the check catches accidental copy of other projects' identifiers. 2. Run `./scripts-run src/scripts/check_references` — cross-file links between the five contexts must resolve. 3. Confirm with the user: "is this accurate enough that a reviewer should treat it as the source of truth?" — anything less and a `<!-- TBD -->` marker stays. ## Output format 1. `agents/settings/contexts/<file>.md` updated with project-specific content; every section either authored or explicitly marked `<!-- TBD: ... -->`. 2. A short summary comment back to the user: which sections are complete, which are `TBD`, and which downstream reviewer skills are now unblocked. 3. Optional: a proposal stub in `agents/learnings/` for any template gap the user hit (missing section, ambiguous field) — feeds the curated self-improvement pipeline via `learning-to-rule-or-skill`. ## Gotcha - The model tends to fabricate plausible roles, fields, or alerts when harvesting comes up empty. Do NOT. An `<!-- TBD: ... -->` marker is always better than a made-up entry — reviewer skills trust this file. - The model tends to collapse the template once it starts editing, losing the HTML comments that explain *why* a section exists. Preserve them until the section is authored — they are the authoring prompt. - `data-sensitivity.md` is the highest-leverage file and also the one most likely to be skipped as "boring". Prioritise it after `auth-model` — missing entries here become production leaks, not review nits. - Do not treat this skill as a form-filler. If a project is single-tenant, `tenant-boundaries.md` SHOULD be deleted, not stubbed — the checklist explicitly says so at the top of the file. ## Path conventions when a context cites another context If the context file declares its own `load_context:` (chain reasoning), use logical names rooted at the source — `contexts/<area>/<file>.md` for package material or `agents/settings/contexts/<file>.md` for project-local material. The `.agent-src.uncondensed/` prefix is rejected by the schema regex and by `scripts/lint_load_context.py`. Body links to `docs/guidelines/...` use the verbatim `../../docs/...` relative form. Canonical reference: `rule-writing` § 3b and `docs/contracts/load-context-schema.md`. ## Frugality Standards Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md) to every context file you author. **Examples in this artifact:** - Per the charter's index nature, context files are reviewer fuel — they hold mechanics, not Iron-Law obligations. - Per the cite-don't-restate principle, when a section mirrors a rule, link the rule and stop. - Per the act-skip-narration rule, lookup tables open the section; explanatory prose follows only if the table is ambiguous. **Pre-save self-check:** 1. Does the context file restate Iron-Law text instead of linking the rule? 2. Does any section open with "This document explains…" instead of the lookup material? 3. Are placeholders (`<add me>`, `TBD`) shipped instead of actual content? 4. Are the cited rules linked with stable anchors (verified to exist)? ## Do NOT - Do NOT copy content between projects. Every context file is local to its repo. Reuse of another project's roles, tenants, or alerts is a portability violation and a security risk. - Do NOT commit TBD-heavy files without flagging them in the PR description. Reviewer skills will downgrade confidence, but a human reviewer should know the contexts are partial. - Do NOT rename or restructure the template sections. Reviewer skills grep for exact headings.