477 lines
26 KiB
Markdown
477 lines
26 KiB
Markdown
# META — TODO (workspace meta-tooling)
|
|
|
|
For known issues see `META_ISSUES.md`.
|
|
|
|
Planned work for the workspace meta-tooling itself: protocol stack, skills, registry conventions, `.github/` files. Distinct from code-domain topics.
|
|
|
|
## Priority legend
|
|
|
|
- **P0** blocker · **P1** important · **P2** nice-to-have · **P3** idea
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-J9N4: `docs-check` skill — runtime discovery for per-repo `TOPIC_CODES.md`
|
|
|
|
**Priority:** P2 · **Type:** Skill enhancement · **Status:** Open · **Area:** `docs-check/SKILL.md` topic-code validation
|
|
**Origin:** Phase 5.1 / LLMP-DEC-58 deferral
|
|
|
|
### Description
|
|
|
|
After Phase 5.1, `TOPIC_CODES.md` became framework-only (ACCORE topics only — see `AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md`). The `docs-check` skill still validates topic codes only against that single file (framework-only nézőpont).
|
|
|
|
When `docs-check` is invoked from a higher-layer repo with its own `<repo>/.github/TOPIC_CODES.md` (e.g., `AyCode.Blazor/.github/TOPIC_CODES.md` declaring `GRID`), the skill currently does NOT find or honour it. Consumer-side topic codes are unrecognized — the skill either falsely flags valid consumer topics as "unknown topic" or skips the validation entirely.
|
|
|
|
### Fix direction
|
|
|
|
Update `docs-check/SKILL.md` Step 5 (Topic code selection) and the topic-loading logic to:
|
|
1. Read framework's `TOPIC_CODES.md` (current behaviour).
|
|
2. Walk the **active repo's** `@repo.own-dep-repos` recursively.
|
|
3. For each walked repo, check if `<repo>/.github/TOPIC_CODES.md` exists; if so, union its topic codes into the active set.
|
|
4. Validate against the merged set.
|
|
|
|
Mirror the runtime-discovery pattern adopted by `protocol-audit` in Phase 5.1 (`protocol-audit/SKILL.md` Step 1).
|
|
|
|
### Acceptance criteria
|
|
|
|
- `docs-check` running from `AyCode.Blazor` recognizes both ACCORE topics (LOG, BIN, ...) AND ACBLAZOR topics (`GRID`).
|
|
- `docs-check` running from `AyCode.Core` only sees ACCORE topics (Framework-First — no awareness of higher layers).
|
|
- No central enumeration of consumer topic registries needed.
|
|
|
|
### Related
|
|
|
|
- LLMP-DEC-58 (Phase 5.1 deferral noted)
|
|
- `protocol-audit/SKILL.md` Step 1 (parallel runtime-discovery design)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-K2P7: `protocol-audit` skill — auto-detect path/anchor mismatches in markdown cross-refs
|
|
|
|
**Priority:** P3 · **Type:** Skill enhancement (new invariant) · **Status:** Open · **Area:** `protocol-audit/SKILL.md`
|
|
**Origin:** Phase 6 (LLMP-DEC-59) — `LOGGING_TODO.md` L88 typo discovered mid-migration
|
|
|
|
### Description
|
|
|
|
A real class of typo: a markdown link's path-part references one file, but the anchor-part refers to an ID belonging to a different file. Example observed pre-Phase-6: `LOGGING_TODO.md` line 88 had `../../../AyCode.Services/docs/SIGNALR/SIGNALR_TODO.md#log-t-5` — path → SIGNALR_TODO.md, but anchor `#log-t-5` is a LOG-T anchor (intent was clearly `#sig-t-5`). The intent-vs-reality mismatch was silent: markdown renderers don't validate cross-file anchor existence; the broken link "looks fine" until clicked.
|
|
|
|
### Fix direction
|
|
|
|
Add a new audit invariant (e.g., `D1` — docs-link integrity, applies to `docs/` files):
|
|
1. Parse all `[text](<path>#<anchor>)` patterns and bare `<file>.md#<anchor>` references in loaded `.md` files.
|
|
2. For each: resolve `<path>` to a target file; extract heading-derived anchors from the target; verify `<anchor>` exists.
|
|
3. FAIL with evidence (file + line) and suggested fix (closest-match anchor in target file).
|
|
|
|
Skill stays read-only; reports findings; user approves any patch (Rule #5).
|
|
|
|
### Acceptance criteria
|
|
|
|
- Catches the `LOGGING_TODO.md` L88 class (different-file mismatched anchor).
|
|
- Catches stale anchors after a renamed heading (anchor exists in old form, target now uses new ID).
|
|
- Low false-positive rate (auto-generated heading anchors resolve correctly per GitHub-flavored markdown rules).
|
|
|
|
### Related
|
|
|
|
- LLMP-DEC-59 (typo fix during Phase 6 — discovery context)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-F8R3: Static-text auto-staleness detection — `Current protocol state` summary AND SKILL.md / registry text drift
|
|
|
|
**Priority:** P3 · **Type:** Skill enhancement · **Status:** Open · **Area:** `protocol-audit/SKILL.md` (or `docs-check/SKILL.md`)
|
|
**Origin:** Phase 6 + LLMP-DEC-60 summary refresh; **scope broadened by LLMP-DEC-64** to include SKILL.md text drift (parallel class)
|
|
|
|
### Description
|
|
|
|
The `Current protocol state (quick reference)` section at the top of `LLM_PROTOCOL_DECISIONS.md` is a mutable snapshot per LLMP-DEC-25 design. After multiple LLMP-DEC entries land, the snapshot drifts from reality.
|
|
|
|
Drift instances observed during the Phase 1-6 migration (all caught only at Phase 6 closure during a manual review):
|
|
- `Active as of 2026-04-24` while LLMP-DEC entries up to 2026-04-26 had been added.
|
|
- `8 instruction files` while LLMP-DEC-51 reduced count to 7.
|
|
- OLD 3-component ID format described while LLMP-DEC-50..59 migrated to 4-component.
|
|
- Skill version labels (`v2.2`, `v1.0`) violating LLMP-DEC-47.
|
|
- `protocol-audit` description still mentioned `references/REPOS.md` central read after LLMP-DEC-58 redesigned to runtime discovery.
|
|
|
|
**Parallel drift class — SKILL.md / invariant text staleness** (LLMP-DEC-64 broadened the scope):
|
|
- `protocol-audit/SKILL.md` C4 invariant said "all three skills" + `[LOADED_DOCS]` counts "4 for primary, 5 for inherit" — outdated since LLMP-DEC-43 introduced 5-skill 2-reactive/3-user-gated matrix (correct counts: 3/4).
|
|
- `protocol-audit/SKILL.md` X1 invariant said "all three bullets must be listed" — same root cause.
|
|
- Caught 2026-04-27 by a re-audit using the post-Phase-5.1 skill itself (positive self-evidence).
|
|
|
|
Manual refresh worked (LLMP-DEC-60 for summary; LLMP-DEC-64 for SKILL.md), but a periodic/automated reminder would catch drift earlier.
|
|
|
|
### Fix direction
|
|
|
|
Two complementary options (pick one or combine), now covering BOTH drift classes:
|
|
|
|
**(a) `protocol-audit` invariant `M1`** (meta-text integrity, optional) — applies to:
|
|
- `LLM_PROTOCOL_DECISIONS.md` `Current protocol state` section claims (date, file count, skill list, ID format).
|
|
- `protocol-audit/SKILL.md` invariant texts that describe protocol-state quantities (e.g., skill counts in C4, bullet-list expectations in X1).
|
|
- Other SKILL.md / registry texts describing "current" state (`docs-check/SKILL.md`, `docs-discovery/SKILL.md`, `REPO_PREFIXES.md`, `TOPIC_CODES.md` cross-link counts).
|
|
|
|
Compare against ground truth (filesystem walk + file content) and surface drift with suggested patch.
|
|
|
|
**(b) `docs-check` skill** flags any of the above as stale if N (e.g., N ≥ 3) new LLMP-DEC entries have been added since the file's last touch — heuristic but catches the common drift pattern.
|
|
|
|
### Acceptance criteria
|
|
|
|
- The drift cases above (date, file count, skill list, ID format, version labels) all detectable.
|
|
- User can mark a known-deferred summary update as `Status: InProgress` to suppress the warning.
|
|
- Low-friction: warning only, never blocking.
|
|
|
|
### Related
|
|
|
|
- LLMP-DEC-25 (summary section design)
|
|
- LLMP-DEC-60 (most recent manual refresh)
|
|
- LLMP-DEC-62 (this META-TODO's introduction)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-B6V2: General-purpose `scheduler` skill — workspace-side scheduled-task abstraction
|
|
|
|
**Priority:** P3 · **Type:** New skill · **Status:** Open · **Area:** new skill (proposed: `AyCode.Core/.github/skills/scheduler/`)
|
|
**Origin:** 2026-04-26 — discussion about `MIGRATION_ID_MAPPING.md` 2026-05-10 deletion-review (LLMP-DEC-58)
|
|
|
|
### Description
|
|
|
|
The current LLMP-DEC-58 retention pattern uses **passive LLM-self-reminding** (any LLM reading the file from 2026-05-10 onward surfaces a deletion prompt). Works only if the file gets read; not guaranteed timing. Anthropic's host environment offers a `schedule` skill (one-time/recurring remote agents) — useful for the specific 2026-05-10 case, but ties the workspace process to a specific host's capability.
|
|
|
|
A **workspace-side `scheduler` skill** would generalize the pattern:
|
|
- File-based registry (e.g., `AyCode.Core/.github/SCHEDULED_TASKS.md` or similar) — declared scheduled events: due-date / cadence + trigger-action + description.
|
|
- Skill scans the registry on session start; surfaces "due / overdue" tasks to the user (gated, not spammy).
|
|
- Host-agnostic (Claude Code, Copilot, future LLM hosts).
|
|
- Optional integration: when the host has a native scheduler, the skill can offer to register the task there too — workspace-side registry stays source of truth.
|
|
|
|
Use cases beyond migration retention:
|
|
- Archive-eligibility scans (`docs-archive` periodic runs).
|
|
- Periodic `protocol-audit` runs.
|
|
- Planned-deletion of transient artifacts (more migrations, generated outputs, etc.).
|
|
- Deadline-bound TODOs that should auto-surface near their date.
|
|
|
|
### Fix direction
|
|
|
|
1. Create skill: `AyCode.Core/.github/skills/scheduler/SKILL.md` (with `references/` for the registry).
|
|
2. Define the registry format — likely simple table (`task-id | type (one-time/recurring) | due-date or cadence | trigger-action | description | status`).
|
|
3. Skill triggers:
|
|
- **Reactive** (session-start scan, like `docs-discovery` / `docs-check`) — surface only if there ARE due/overdue tasks.
|
|
- **User-invoked**: "list scheduled tasks", "what's due", "schedule a task" (interview-style add).
|
|
4. Migrate the 2026-05-10 `MIGRATION_ID_MAPPING.md` deletion-review to this system once it exists; the per-file LLM-self-reminder header note then trims to a cross-ref pointing at the registry.
|
|
|
|
### Acceptance criteria
|
|
|
|
- Registry-driven, host-agnostic.
|
|
- Session-start surfacing of due / overdue tasks (low-friction, not noise).
|
|
- Optional one-click "register at host-native scheduler too" for hosts that support it.
|
|
- The 2026-05-10 deletion-review event migrated to this system as the inaugural entry.
|
|
|
|
### Related
|
|
|
|
- LLMP-DEC-58 (introduces the per-file LLM-self-reminder pattern this would replace).
|
|
- LLMP-DEC-43 (5-skill matrix — adding a 6th skill is a workspace-meta change; will need an LLMP-DEC entry when implemented).
|
|
- Anthropic-host `schedule` skill (parallel capability to integrate with, not replace).
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-M5T8: TL;DR / "When to read this file" block on every topic README
|
|
|
|
**Priority:** P2 · **Type:** Convention update + bulk doc edit · **Status:** Open · **Area:** All topic `<TOPIC>/README.md` files
|
|
**Origin:** 2026-04-26 — Cross-source convergence (3/3 Copilot reviewers + my own analysis); user-reframing strengthened the case (correctness > token-economy)
|
|
|
|
### Description
|
|
|
|
Topic README files (`LOGGING/README.md`, `BINARY/README.md`, etc.) currently vary in opening style. The agent has to scan the whole README to decide "is this topic relevant?", "which sister docs to load deeper?", "when is this NOT what I'm looking for?". A consistent **TL;DR / "When to read" block** at the top would make load-decisions cheaper and more accurate. **3-of-3 Copilot reviewer convergence** is unusually strong signal.
|
|
|
|
Anti-hallucination angle: the block helps agents pick the RIGHT topic to load, not just MORE topics — relevance still matters even under "load broader" preference (`ACCORE-META-T-R2W6`).
|
|
|
|
### Fix direction
|
|
|
|
Standardize a block at the top of every topic README (after `# Title`, before first `## ` section):
|
|
|
|
```markdown
|
|
> **Mikor olvasd ezt a fájlt:** ha a kérdés érinti `<X>`, `<Y>`, `<Z>`.
|
|
> **Először olvass:** `<TOPIC>_<sub>.md`, `<TOPIC>_<sub2>.md` (a 80% case-eket fedik).
|
|
> **Mikor NE olvasd:** ha pl. csak `<other-concern>` → `<other-topic>/README.md`.
|
|
```
|
|
|
|
Apply to all ACCORE topic READMEs (BINARY, LOGGING, SIGNALR, SBP, TOON, XCUT, AUTH). Pattern propagates to higher-layer repos as their topic READMEs are written.
|
|
|
|
### Acceptance criteria
|
|
|
|
- Every ACCORE topic README has the block, formatted consistently.
|
|
- The block is referenced in `docs-discovery/SKILL.md` as a load-decision aid.
|
|
- Optional: `docs-check` invariant flags missing block on new topic READMEs.
|
|
|
|
### Related
|
|
|
|
- Cross-source: 3-of-3 Copilot reviewer convergence (Set 2 #1+#2, Set 3 #2)
|
|
- LLMP-DEC-21 (Pattern B docs layout — established the topic-README pattern)
|
|
- `ACCORE-META-T-Y4Q9` (Hot-path tagging — finer-grained version of the same idea)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-Y4Q9: Hot-path / Fast-path tagging in topic READMEs
|
|
|
|
**Priority:** P3 · **Type:** Convention update · **Status:** Open · **Area:** Topic README files
|
|
**Origin:** 2026-04-26 — Set 3 #3 reviewer suggestion; user-reframing recalibrated importance to **secondary** (less critical when default is "load more")
|
|
|
|
### Description
|
|
|
|
The TL;DR (`ACCORE-META-T-M5T8`) lists the FIRST 2-3 docs to load. A `### Fast-path docs` sub-section (or `@fastpath` tag) declaratively marks the docs covering the 80% case — distinct from "Először olvass" (which is conversational guidance) by being machine-friendly + parsable.
|
|
|
|
User's recalibration: with "load more upfront" preference (`ACCORE-META-T-R2W6`), agent will tend to load broader anyway → fast-path tagging becomes **secondary**, not critical. Still useful as a SIGNAL for which docs to start with when the agent does decide to be selective.
|
|
|
|
### Fix direction
|
|
|
|
Add a small `### Fast-path docs` section in topic READMEs listing 2-3 docs that suffice for 80% of agent queries. Example:
|
|
|
|
```markdown
|
|
### Fast-path docs
|
|
- `BINARY_FORMAT.md` — wire format spec (most queries land here)
|
|
- `BINARY_OPTIONS.md` — configuration reference
|
|
- `BINARY_WRITERS.md` — IBufferWriter integration
|
|
```
|
|
|
|
`docs-discovery/SKILL.md` honours: when topic identified, fast-path docs load first; expanded set (full topic-pair + sister docs) on demand or per `R2W6` preference.
|
|
|
|
### Acceptance criteria
|
|
|
|
- ACCORE topic READMEs have the block where applicable.
|
|
- `docs-discovery/SKILL.md` parses and honours the fast-path.
|
|
- Marker convention defined and consistent.
|
|
|
|
### Related
|
|
|
|
- `ACCORE-META-T-M5T8` (TL;DR — predecessor / parent convention)
|
|
- Cross-source: Set 3 #3 (only 1 source mentioned this — weaker convergence than M5T8)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-V7L2: ADR quality lint / structural validator
|
|
|
|
**Priority:** P3 · **Type:** Skill enhancement · **Status:** Open · **Area:** `adr-author/SKILL.md` Step 8 extension (or new Step 10) + optional `references/ADR_LINT.md`
|
|
**Origin:** 2026-04-26 — Set 1 #7 + 2-of-3 Copilot reviewer agreement (one explicit suggestion: warning, not hard-fail)
|
|
|
|
### Description
|
|
|
|
`adr-author/SKILL.md` Steps 5-8 produce ADRs but don't VALIDATE them post-write. A lint pass would catch:
|
|
- Missing required sections (`## Status`, `## Context`, `## Decision`, `## Consequences`, `## Alternatives considered`, `## Related`)
|
|
- Status field format: `Proposed (YYYY-MM-DD) | Accepted (...) | Superseded by ADR-XXXX | Rejected (...)`
|
|
- Alternatives section: ≥ 2 alternatives present (or explicit "no alternatives — implementation path" justification)
|
|
- Decision section: explicit decision criterion, not just "we'll do X" without why
|
|
- Cross-ref consistency: `Supersedes` / `Superseded by` / `Related ADRs` IDs valid (file exists, anchor exists)
|
|
|
|
### Fix direction
|
|
|
|
Add Step 10 to `adr-author/SKILL.md` (or extend Step 8): after Write, run lint over the generated ADR. Surface any FAIL as polite suggestion (**warning mode**, not blocker — per Copilot reviewer #2).
|
|
|
|
Could alternatively be a `protocol-audit` invariant `D2` (docs-link integrity) extended to validate ADR structure — synergy with `ACCORE-META-T-K2P7` (path/anchor mismatch detection).
|
|
|
|
### Acceptance criteria
|
|
|
|
- Generated ADRs pass lint by construction (if user fills in placeholders correctly).
|
|
- Lint reports are constructive (suggested fix, not just "FAIL").
|
|
- Doesn't block ADR creation — quality nudge, not gate.
|
|
|
|
### Related
|
|
|
|
- `adr-author/SKILL.md` Steps 5-8 (existing structure)
|
|
- `ACCORE-META-T-K2P7` (parallel "anchor mismatch" lint family — synergy candidate)
|
|
- Cross-source: Set 1 #7 + Copilot reviewer #2 ("warning, not hard fail")
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-N8K3: `Last verified against commit` opt-in metadata field
|
|
|
|
**Priority:** P3 · **Type:** Convention (opt-in metadata) · **Status:** Open · **Area:** Long-form `docs/` files (opt-in only)
|
|
**Origin:** 2026-04-26 — Set 2 #3 + user anti-hallucination framing (drift detection prevents stale-context hallucination loops)
|
|
|
|
### Description
|
|
|
|
Drift between `.md` docs and source code is a real hallucination cause: agent reads a doc, trusts it, the doc was written 6 months ago against an old API → wrong answer. A simple `<!-- last-verified: <commit-hash> @ <YYYY-MM-DD> -->` HTML-comment metadata field would let the agent know:
|
|
|
|
- "This doc was verified against commit `cdd54d3` (2026-04-05) — current HEAD is later — possibly stale, double-check the relevant `.cs` file."
|
|
- vs. "Verified yesterday — trust it."
|
|
|
|
User's recalibration: anti-hallucination angle **strengthens** this entry's importance vs. the original "marginal utility" framing. Drift-detection IS hallucination prevention.
|
|
|
|
### Fix direction
|
|
|
|
**Opt-in only** — not all docs need this. Suggested for:
|
|
- Long-form architecture docs (`ARCHITECTURE.md`, `BINARY/README.md`, etc. — less frequent churn)
|
|
- Reference docs (`CONVENTIONS.md`, `GLOSSARY.md`)
|
|
- Stable API docs / wire-format docs
|
|
|
|
NOT for:
|
|
- TODO / ISSUES files (high churn — verification not meaningful)
|
|
- Decision Log / ADRs (immutable per LLMP-DEC governance)
|
|
|
|
Format: HTML-comment line at top: `<!-- last-verified: <commit-hash> @ <YYYY-MM-DD> -->`. Manual update by author on doc-modifying response. `docs-check` skill flags "doc with last-verified tag, age > N days, code path touched since" as a soft warning.
|
|
|
|
### Acceptance criteria
|
|
|
|
- Convention documented in `CONVENTIONS.md` or `META_ISSUES.md` reference section.
|
|
- Opt-in — never required, never auto-fail.
|
|
- `docs-check` skill respects the marker if present.
|
|
- Anti-hallucination value: agent expresses "stale, verifying" instead of guessing.
|
|
|
|
### Related
|
|
|
|
- Set 2 #3 (Copilot suggestion)
|
|
- `ACCORE-META-T-R2W6` (anti-hallucination framing motivates this)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-P9F4: Pre-load expansion with foundational reference docs
|
|
|
|
**Priority:** P2 · **Type:** Protocol change (Session Setup section + Rule #1) · **Status:** Open · **Area:** `copilot-instructions.md` Session Setup + `docs-discovery/SKILL.md`
|
|
**Origin:** 2026-04-26 — User reframing (correctness > token-economy); current 3-file pre-load may be too narrow
|
|
|
|
### Description
|
|
|
|
Current session-start pre-load is **3 files** (per LLMP-DEC-43): the active repo's `copilot-instructions.md` + 2 reactive skill SKILL.md (`docs-discovery`, `docs-check`). The 3 user-gated skills lazy-load on demand.
|
|
|
|
User feedback: this is too narrow. Foundational reference docs (`ARCHITECTURE.md`, `GLOSSARY.md`, `CONVENTIONS.md`, top-level project `README.md`) get queried in nearly every session. Lazy-loading them per-turn means each topic-specific question pays the load cost separately. **Pre-loading at session-start amortizes once across the entire session.**
|
|
|
|
User cost function (explicit): 5-8K extra session-start tokens are CHEAPER than 1 hallucination loop caused by missing foundational context.
|
|
|
|
### Fix direction
|
|
|
|
Expand session-start pre-load to include foundational reference docs from active repo's `docs/` root (when they exist):
|
|
|
|
1. Active repo's `copilot-instructions.md` (current — keeps Rule #1 baseline)
|
|
2. `docs-discovery/SKILL.md` (current — reactive)
|
|
3. `docs-check/SKILL.md` (current — reactive)
|
|
4. Active repo's root `README.md` (NEW)
|
|
5. `docs/ARCHITECTURE.md` (NEW, if exists)
|
|
6. `docs/CONVENTIONS.md` (NEW, if exists)
|
|
7. `docs/GLOSSARY.md` (NEW, if exists — workspace-glossary)
|
|
|
|
Result: 4-7 files at session start (depending on which exist in the active repo). LOADED_DOCS prefix shows accurate count. `## Session Setup` section in `copilot-instructions.md` updated.
|
|
|
|
For inherit files: pre-load also AyCode.Core's foundational docs (since this repo doesn't host them) — adjust the count similarly.
|
|
|
|
### Acceptance criteria
|
|
|
|
- Session-start LOADED_DOCS count: 4-7 files (was 3).
|
|
- Foundational docs available without explicit user query → reduces "had to grep for context" loops.
|
|
- `docs-check`'s base context broader → more accurate drift detection.
|
|
- Skill descriptions and Session Setup section in `copilot-instructions.md` updated.
|
|
- LLMP-DEC entry recording the change (refines LLMP-DEC-43).
|
|
|
|
### Related
|
|
|
|
- LLMP-DEC-43 (current 5-skill matrix with 2 reactive pre-loaded)
|
|
- `ACCORE-META-T-R2W6` (user-preference statement — same anti-hallucination motivation)
|
|
- LLMP-DEC-58 / 60 (Framework-First retightening — pre-load expansion respects this: only same-or-lower-layer docs)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-R2W6: Workspace user-preference statement (correctness > token-economy)
|
|
|
|
**Priority:** P2 · **Type:** Protocol change (new sub-rule or `## Workspace Load-Policy Preference` section) · **Status:** Open · **Area:** `copilot-instructions.md`
|
|
**Origin:** 2026-04-26 — User reframing of cost function: *"felesleges kör költsége >> tokenköltség. inkább több, mint hibás."*
|
|
|
|
### Description
|
|
|
|
The current AI AGENT CORE PROTOCOL implicitly assumes "minimize tokens" as a calibration goal. User's actual cost function is different:
|
|
|
|
> "Felesleges kör költsége >> tokenköltség. Inkább több, mint hibás."
|
|
|
|
Agent should **prefer reading docs over guessing** when uncertain. The amortization principle (LLMP-DEC-43 era) partially codifies this for session-start; doesn't extend explicitly to per-turn decisions.
|
|
|
|
Without an explicit preference statement, agents calibrate toward "minimum loading" defaults observed in their training. The workspace's actual preference is opposite: **load broader, ask when unsure, never guess critical context**.
|
|
|
|
### Fix direction
|
|
|
|
Add a new section / Rule sub-bullet to `copilot-instructions.md` (location TBD: Rule #2 extension, new Rule #7, or a `## Workspace Load-Policy Preference` section between `## Session Setup` and the Rules). Suggested text:
|
|
|
|
```
|
|
**WORKSPACE LOAD-POLICY PREFERENCE:** This workspace prioritizes correctness
|
|
over token-economy. When uncertain whether you have current/sufficient
|
|
context on a topic, READ the relevant `.md` file first — do NOT guess from
|
|
memory or attempt to infer purely from code-search. Loading 5-10K extra
|
|
tokens upfront is cheaper than a wrong answer that requires user correction
|
|
+ retry. The amortization principle extends to ALL turns, not just session
|
|
start: every turn has the choice between (a) read-then-answer and (b)
|
|
guess-then-maybe-be-wrong; default to (a).
|
|
|
|
This explicit preference shifts agent calibration toward "load when uncertain".
|
|
It does NOT mean "load everything" — relevance still matters (Rule #2's docs-
|
|
before-code stays). It means "within the relevance scope, prefer broader
|
|
loading over narrower".
|
|
```
|
|
|
|
### Acceptance criteria
|
|
|
|
- Rule text in AyCode.Core canonical `copilot-instructions.md` (inherited by reference for non-Core primary files, or duplicated to all 5 — TBD per protocol-audit invariant style).
|
|
- `docs-discovery/SKILL.md` and `docs-check/SKILL.md` reference this preference where it affects skill behaviour (cap revisit per `ACCORE-META-T-C5J7`).
|
|
- LLMP-DEC entry recording the codification.
|
|
|
|
### Related
|
|
|
|
- `ACCORE-META-T-P9F4` (pre-load expansion — direct application)
|
|
- `ACCORE-META-T-C5J7` (cap revision — also direct application)
|
|
- LLMP-DEC-43 (amortization principle — this preference extends it)
|
|
- `ACCORE-META-T-N8K3` (drift-detection — anti-hallucination companion)
|
|
|
|
---
|
|
|
|
## ACCORE-META-T-C5J7: `docs-check` and `docs-discovery` cap revision (revisit fixed limits)
|
|
|
|
**Priority:** P3 · **Type:** Skill behaviour tuning · **Status:** Open · **Area:** `docs-check/SKILL.md` (volume cap), `docs-discovery/SKILL.md` (per-topic limit)
|
|
**Origin:** 2026-04-26 — User reframing; LLMP-DEC-27 (volume cap = 3) calibration revisit
|
|
|
|
### Description
|
|
|
|
`docs-check/SKILL.md` has a "max 3 items per response" volume cap (per LLMP-DEC-27, originally calibrated for "noise-aversion / silence beats noise"). `docs-discovery/SKILL.md` has per-topic file limits implicit in glob patterns.
|
|
|
|
User's recalibration: the noise-averse 3-cap may be too conservative under the "correctness > token-economy" preference (`ACCORE-META-T-R2W6`). Options:
|
|
|
|
1. **Higher fixed default** (e.g., 5 or 7) — simple, predictable.
|
|
2. **Confidence-based** (no cap if all proposals are high-confidence with quotable evidence; cap kicks in only when speculation creeps in) — better quality control but harder to calibrate.
|
|
3. **Configurable per session** via a marker — flexible but adds state.
|
|
|
|
NOT dynamic complexity-based tuning (rejected per Set 1 #1 skip rationale — inconsistent across agents).
|
|
|
|
### Fix direction
|
|
|
|
Two-step exploration:
|
|
1. Update `docs-check/SKILL.md` volume cap: try `max 5` instead of `max 3`. Observe over a few sessions: is signal/noise ratio better, worse, same?
|
|
2. If "better" → codify as new default with LLMP-DEC entry refining LLMP-DEC-27. If "worse" → revert and consider confidence-based alternative.
|
|
|
|
For `docs-discovery/SKILL.md`: revisit per-topic file limit. Currently glob loads paired main+ISSUES+TODO. Consider expanding to load related sub-topic docs by default if they exist (e.g., `LOGGING/README.md` triggers also loads `LOGGING_SERVER.md` if present).
|
|
|
|
### Acceptance criteria
|
|
|
|
- Cap is documented numerically (no vague "as many as needed").
|
|
- `docs-check` skill respects new cap.
|
|
- LLMP-DEC entry recording the cap change (refines LLMP-DEC-27).
|
|
- A short session-log validates the new cap doesn't introduce noise (signal/noise ≥ pre-change).
|
|
|
|
### Related
|
|
|
|
- LLMP-DEC-27 (original 3-cap rationale — "silence beats noise")
|
|
- `ACCORE-META-T-R2W6` (preference shift — motivates this)
|
|
- `ACCORE-META-T-P9F4` (pre-load expansion — parallel "load more" direction)
|
|
|
|
---
|
|
|
|
## TODO entry template
|
|
|
|
```
|
|
## ACCORE-META-T-XXXX: Short title
|
|
|
|
**Priority:** P0 / P1 / P2 / P3 · **Type:** Skill enhancement / Convention update / Registry change / Docs / Cleanup · **Status:** Open / InProgress / Closed (YYYY-MM-DD) · **Area:** <skill or registry name>
|
|
**Origin:** <where the need was observed — Phase X / specific incident / LLMP-DEC-N>
|
|
|
|
### Description
|
|
What needs to be done and why, with quotable evidence (file paths, behaviour observation, etc.).
|
|
|
|
### Fix direction
|
|
Proposed approach.
|
|
|
|
### Acceptance criteria
|
|
- Concrete observable outcomes.
|
|
|
|
### Related
|
|
- Sibling: `META_ISSUES.md#accore-meta-i-xxxx` (if a known issue spawned this TODO)
|
|
- LLMP-DEC: `LLMP-DEC-N` (if a decision motivated this work)
|
|
```
|