Defame1297
c705a38809
Produces docs/notes/skill-implementation-workflow.md with agreed conventions for all Chunk 3 skill issues (0017–0028). Key decisions: - Per-skill process: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check vs constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively - Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored, phase 2 of 0018) → everything else - Upstream review changed from per-chunk-start to per-skill - `when:` and `references:` frontmatter fields added to authoring standard - Sub-agent usage prescribed as named steps in the workflow - HITL: human reviewed and approved conventions Updates: PRD implementation decisions; issues 0016–0028 with specific acceptance criteria; docs/spec/overview.md; ROADMAP Chunk 3 housekeeping note (bootstrap order, cadence, acceptance criteria status); CONTEXT.md Source field (per-skill cadence, references: companion field); LESSONS.md with three patterns from the grill session. Post-grill additions (same session): Step 6 (session handoff) added to the workflow; handoff section appended to issue 0016; handoff checklist item added to Chunk 3 closure issue (0028). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
40 lines
5.4 KiB
Markdown
40 lines
5.4 KiB
Markdown
# Lessons
|
|
|
|
Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule.
|
|
|
|
**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/git.md` for git conventions, or `core/instructions/testing.md` for testing conventions. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
|
|
|
|
**Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
|
|
|
|
**What belongs here:** Non-obvious observations — a rule that was misapplied, a pattern that caused friction, a decision that turned out wrong in practice. Not summaries of what was built (that's git history) or planned changes (that's issues).
|
|
|
|
---
|
|
|
|
## 2026-05-17 — Workflow documents should prescribe sub-agent usage, not just allow it
|
|
|
|
When writing workflow documents (like `docs/notes/skill-implementation-workflow.md`), the natural tendency is to describe steps at a high level and leave sub-agent usage as an implementation detail. But if the workflow doesn't explicitly prescribe "spawn a sub-agent here," practitioners default to doing everything in the main context — accumulating token cost and losing the isolation benefit. Fix: make sub-agent usage a named step in the workflow, specifying what the agent receives, what it returns, and why it's isolated. This makes the workflow reproducible rather than dependent on the practitioner remembering to use agents.
|
|
|
|
## 2026-05-17 — Conflict check before synthesis grill, not during
|
|
|
|
When combining upstream sources into a skill, conflicts with governing documents (AI constitution, factory principles) tend to surface in the middle of the synthesis grill — disrupting the combining discussion and requiring context switches. Fix: run a dedicated conflict-check step before the grill. A sub-agent reads the governing documents, checks the upstream content against them, and returns a numbered list of tensions. The grill then starts with those items as explicit agenda points, making it faster and more systematic. An empty conflict list is also valuable — it confirms the upstreams are clean before co-writing begins.
|
|
|
|
## 2026-05-17 — Cross-references to "produced by issue N" rot before the session ends
|
|
|
|
Issue files frequently referenced "the workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016)." Within the same session that closes issue 0016, that parenthetical is already stale — the document exists and is the authoritative reference. Fix: reference the document path directly, not the issue that produced it. The git history records the producing issue; cross-references should point to the artifact that persists.
|
|
|
|
## 2026-05-17 — "Read at session start" is a behavioral hope, not a guarantee
|
|
|
|
The repo CLAUDE.md instructs agents to read CONTEXT.md and ROADMAP.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context. ROADMAP stays on-demand.
|
|
|
|
## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity
|
|
|
|
Behavioral tests (2026-05-17) showed three communication/behavior rules failing: exploratory question format (gave verbose multi-bullet answer instead of 2-3 sentences), file edit intent (asked for clarification instead of stating intent and proceeding), and push confirmation (went straight to tool call instead of asking first). All three rules are present in `providers/claude-code/CLAUDE.md` as one-liner statements. The RLHF-trained defaults (thorough answers, risk-averse clarification seeking, fast execution) consistently outcompete thin rules. Fix: rewrite failing rules with specificity, a counter-example, and a boundary statement — not just a single-line imperative.
|
|
|
|
## 2026-05-17 — Secrets rule gap: response text not covered
|
|
|
|
The secrets prohibition in `core/instructions/governance.md` fired correctly when asked to write a password to a file, but the agent then reproduced the literal credential in its response text (in a shell `export` example). The rule was interpreted as "don't write to files" not "don't output at all." Fix: the rule needs to explicitly state "never produce the credential value in any output" and give an example showing placeholder usage (`export DB_PASSWORD='<your-password>'`).
|
|
|
|
## 2026-05-17 — HITL gap: agent delegates confirmation to permission system
|
|
|
|
The agent-level HITL rule ("require explicit confirmation before irreversible shared-state operations") is being bypassed: the agent calls the tool and lets the permission dialog catch it. This means the rule is not firing in agent reasoning — it's the permission system acting as a safety net. If a user selects "don't ask again," the net disappears. Fix: the HITL rule needs to be framed as "do not call the tool" rather than "ask before proceeding" — the agent must ask first, then act only after explicit confirmation.
|