Skip to content
This repository was archived by the owner on Jan 2, 2026. It is now read-only.

Commit e6b08e3

Browse files
zircoteclaude
zircote
and
claude
committed
feat(guidance): restructure templates for behavioral prompting
Based on context engineering research, restructure guidance templates to prioritize active operating behaviors over reference documentation. Key changes: - Rename root element from <response_guidance> to <session_operating_context> - Add <active_behaviors> section FIRST with trigger-based capture instructions - Add <memory_recall_behaviors> section for surfacing retrieved memories - Move syntax reference to lower-priority <reference> section - Add recall_notice element when memories are retrieved - Add memories_retrieved attribute to memory_context root Template structure now follows priority order: 1. Active behaviors (WHEN to capture) 2. Memory recall behaviors (HOW to surface memories) 3. Examples (show behavior in action) - detailed only 4. Reference (syntax documentation) This addresses the gap where Claude knew the capture syntax but was not naturally using it during work - the behavioral framing creates context architecture that makes captures feel native to the workflow. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 427c936 commit e6b08e3

5 files changed

Lines changed: 201 additions & 209 deletions

File tree

‎src/git_notes_memory/hooks/context_builder.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -288,15 +288,31 @@ def to_xml(self, context: MemoryContext) -> str:
288288
</commands>
289289
</memory_context>
290290
"""
291+
# Calculate total memory count
292+
total_memories = context.working_memory.count + context.semantic_context.count
293+
291294
attrs = {
292295
"project": context.project,
293296
"timestamp": context.timestamp.isoformat(),
297+
"memories_retrieved": str(total_memories),
294298
}
295299
if context.spec_id:
296300
attrs["spec"] = context.spec_id
297301

298302
builder = XMLBuilder("memory_context", attrs)
299303

304+
# Add visual header when memories are present
305+
if total_memories > 0:
306+
builder.add_element(
307+
"root",
308+
"recall_notice",
309+
text=(
310+
f"Retrieved {total_memories} memories from prior sessions. "
311+
"Reference these when relevant to the current task."
312+
),
313+
priority="high",
314+
)
315+
300316
# Build working memory section
301317
self._add_working_memory_xml(builder, context.working_memory)
302318

‎src/git_notes_memory/hooks/templates/guidance_detailed.xml‎

Lines changed: 80 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,89 @@
1-
<response_guidance level="detailed">
2-
<capture_patterns title="How to Structure Responses for Memory Capture">
3-
<pattern type="decision">
4-
<description>When making architectural or design decisions</description>
5-
<template><![CDATA[**Decision**: [One-line summary]
6-
**Context**: [Why this decision was needed]
7-
**Choice**: [What was chosen]
8-
**Rationale**: [Why this choice over alternatives]
9-
**Alternatives considered**: [Other options evaluated]]]></template>
10-
<trigger_phrases>
11-
<phrase>We decided to...</phrase>
12-
<phrase>The decision is to...</phrase>
13-
<phrase>Going with X because...</phrase>
14-
<phrase>After evaluating, we chose...</phrase>
15-
</trigger_phrases>
16-
</pattern>
17-
<pattern type="learning">
18-
<description>When discovering insights or TIL moments</description>
19-
<template><![CDATA[**Learning**: [One-line insight]
20-
**Context**: [How this was discovered]
21-
**Application**: [When/how to apply this]]]></template>
22-
<trigger_phrases>
23-
<phrase>TIL...</phrase>
24-
<phrase>Discovered that...</phrase>
25-
<phrase>Learned that...</phrase>
26-
<phrase>Turns out...</phrase>
27-
<phrase>Interesting finding...</phrase>
28-
</trigger_phrases>
29-
</pattern>
30-
<pattern type="blocker">
31-
<description>When encountering obstacles or issues</description>
32-
<template><![CDATA[**Blocker**: [One-line issue]
33-
**Impact**: [What this blocks]
34-
**Status**: [investigating/blocked/resolved]
35-
**Resolution**: [If resolved, how]]]></template>
36-
<trigger_phrases>
37-
<phrase>Blocked by...</phrase>
38-
<phrase>Cannot proceed because...</phrase>
39-
<phrase>Stuck on...</phrase>
40-
<phrase>Issue discovered...</phrase>
41-
<phrase>Problem found...</phrase>
42-
</trigger_phrases>
43-
</pattern>
44-
<pattern type="progress">
45-
<description>When completing milestones or deliverables</description>
46-
<template><![CDATA[**Completed**: [What was finished]
47-
**Deliverables**: [Concrete outputs]
48-
**Next**: [What comes next]]]></template>
49-
<trigger_phrases>
50-
<phrase>Completed...</phrase>
51-
<phrase>Finished implementing...</phrase>
52-
<phrase>Milestone reached...</phrase>
53-
<phrase>Done with...</phrase>
54-
<phrase>Successfully implemented...</phrase>
55-
</trigger_phrases>
56-
</pattern>
57-
</capture_patterns>
1+
<session_operating_context level="detailed">
2+
<!-- SECTION 1: ACTIVE OPERATING BEHAVIORS (highest priority) -->
3+
<active_behaviors title="Memory Capture Behaviors">
4+
<behavior trigger="making_decision" priority="critical">
5+
When you make an architectural or design decision, IMMEDIATELY document it.
6+
Format: [decision] One-line summary: rationale
587

59-
<inline_markers title="Quick Capture Markers">
60-
<marker syntax="[remember] text" namespace="learnings" description="Quick capture to learnings"/>
61-
<marker syntax="[remember:namespace] text" namespace="specified" description="Capture to specific namespace"/>
62-
<marker syntax="[capture] text" namespace="auto-detect" description="Auto-detect namespace from content"/>
63-
<marker syntax="[capture:decisions] text" namespace="decisions" description="Capture decision explicitly"/>
64-
<marker syntax="@memory text" namespace="auto-detect" description="Alternative inline syntax"/>
65-
<marker syntax="@memory:patterns text" namespace="patterns" description="Alternative with namespace"/>
66-
</inline_markers>
8+
This is not optional. Decisions made during implementation are easily lost
9+
when context compacts. Capture them as they happen.
10+
</behavior>
11+
<behavior trigger="discovering_insight" priority="critical">
12+
When you discover something surprising, learn a pattern, or have a TIL moment,
13+
capture it immediately:
14+
[learned] What you discovered and why it matters
6715

68-
<valid_namespaces>decisions, learnings, blockers, progress, patterns, research, reviews, retrospective, inception, elicitation</valid_namespaces>
16+
These insights are often forgotten by the next session.
17+
</behavior>
18+
<behavior trigger="hitting_blocker" priority="high">
19+
When blocked on a problem or encountering an issue:
20+
[blocker] What blocks progress + what's needed to unblock
6921

70-
<memory_recall title="How to Use Retrieved Memories">
71-
<instruction priority="high">When memories are provided in memory_context, actively reference them when relevant to the user's task</instruction>
72-
<instruction priority="high">If past decisions or learnings apply to current work, mention them: "Based on a previous decision..." or "You learned earlier that..."</instruction>
73-
<instruction>When blockers from memory_context match current issues, surface the resolution if available</instruction>
74-
<instruction>Use memory IDs when referencing specific memories so users can look them up</instruction>
75-
</memory_recall>
22+
When resolved, update: [learned] How the blocker was resolved
23+
</behavior>
24+
<behavior trigger="completing_milestone" priority="normal">
25+
When completing significant work:
26+
[progress] What was accomplished
27+
</behavior>
28+
</active_behaviors>
7629

77-
<best_practices title="Memory Capture Best Practices">
78-
<practice>Use clear trigger phrases at the start of memorable content</practice>
79-
<practice>Include rationale with decisions, not just the choice</practice>
80-
<practice>Tag blockers with resolution status when solved</practice>
81-
<practice>Keep summaries under 100 characters for better signal detection</practice>
82-
<practice>Use namespace hints when content clearly belongs to a specific category</practice>
83-
</best_practices>
30+
<!-- SECTION 2: MEMORY RECALL BEHAVIORS (highest priority) -->
31+
<memory_recall_behaviors title="How to Surface Retrieved Memories">
32+
<behavior priority="critical">
33+
When memories appear in memory_context below, ACTIVELY reference them.
34+
Don't just silently read them - weave them into your response:
35+
"Based on a previous decision to use PostgreSQL..."
36+
"You learned earlier that pytest fixtures with module scope share state..."
37+
</behavior>
38+
<behavior priority="critical">
39+
If past blockers match current issues, surface the resolution.
40+
Say: "This looks similar to a previous blocker (memory ID) which was resolved by..."
41+
</behavior>
42+
<behavior priority="high">
43+
Memories are prior context, not just data. Use them like you would
44+
remember a conversation - naturally reference relevant parts.
45+
</behavior>
46+
</memory_recall_behaviors>
8447

85-
<examples title="Effective Capture Examples">
86-
<example type="decision">
87-
<input>We need to pick a database</input>
88-
<output><![CDATA[**Decision**: Use PostgreSQL for persistence
89-
**Context**: Need ACID compliance and JSON support
90-
**Choice**: PostgreSQL 15 with JSONB columns
91-
**Rationale**: Team expertise, proven reliability, excellent JSON support
92-
**Alternatives considered**: MongoDB (no ACID), SQLite (scaling concerns)]]></output>
48+
<!-- SECTION 3: EXAMPLES (show the behavior in action) -->
49+
<examples title="Capture in Action">
50+
<example context="During architecture discussion">
51+
Claude output:
52+
"We'll use JWT tokens for authentication because they're stateless and scale well.
53+
[decision] Using JWT for auth: stateless, scales to multiple servers, team has experience"
9354
</example>
94-
<example type="learning">
95-
<input>Found a pytest quirk</input>
96-
<output><![CDATA[**Learning**: pytest fixtures with scope="module" share state across tests
97-
**Context**: Discovered when tests failed intermittently due to shared mock state
98-
**Application**: Use scope="function" for mutable fixtures, module for readonly]]></output>
55+
<example context="After discovering a pattern">
56+
Claude output:
57+
"Interesting - the tests were flaky because of shared fixture state.
58+
[learned] pytest module-scoped fixtures share state across tests - use function scope for mutable fixtures"
9959
</example>
100-
<example type="inline_marker">
101-
<input>Quick insight during coding</input>
102-
<output>[remember:patterns] Always use frozen dataclasses for immutable models to prevent accidental mutation</output>
60+
<example context="When hitting an issue">
61+
Claude output:
62+
"Can't proceed with the migration - the schema has circular dependencies.
63+
[blocker] Schema migration blocked by circular FK dependencies between users and organizations tables"
10364
</example>
10465
</examples>
105-
</response_guidance>
66+
67+
<!-- SECTION 4: REFERENCE (lower priority) -->
68+
<reference title="Capture Syntax Reference">
69+
<inline_markers>
70+
<marker syntax="[decision] text" namespace="decisions"/>
71+
<marker syntax="[learned] text" namespace="learnings"/>
72+
<marker syntax="[blocker] text" namespace="blockers"/>
73+
<marker syntax="[progress] text" namespace="progress"/>
74+
<marker syntax="[remember] text" namespace="learnings"/>
75+
<marker syntax="[remember:namespace] text" namespace="specified"/>
76+
</inline_markers>
77+
<valid_namespaces>decisions, learnings, blockers, progress, patterns, research, reviews, retrospective</valid_namespaces>
78+
79+
<structured_templates title="For Detailed Captures">
80+
<template type="decision"><![CDATA[**Decision**: [One-line summary]
81+
**Context**: [Why this decision was needed]
82+
**Choice**: [What was chosen]
83+
**Rationale**: [Why this choice over alternatives]]]></template>
84+
<template type="learning"><![CDATA[**Learning**: [One-line insight]
85+
**Context**: [How this was discovered]
86+
**Application**: [When/how to apply this]]]></template>
87+
</structured_templates>
88+
</reference>
89+
</session_operating_context>

‎src/git_notes_memory/hooks/templates/guidance_minimal.xml‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
1-
<response_guidance level="minimal">
2-
<inline_markers title="Quick Capture Markers">
3-
<marker syntax="[remember] text" description="Capture to learnings namespace"/>
4-
<marker syntax="[remember:namespace] text" description="Capture to specified namespace"/>
5-
<marker syntax="[capture] text" description="Auto-detect namespace from content"/>
6-
<marker syntax="@memory text" description="Alternative capture syntax"/>
7-
<marker syntax="@memory:namespace text" description="Alternative with namespace"/>
8-
</inline_markers>
9-
<namespaces>decisions, learnings, blockers, progress, patterns, research, reviews, retrospective</namespaces>
10-
</response_guidance>
1+
<session_operating_context level="minimal">
2+
<active_behaviors>
3+
<behavior>When deciding: [decision] rationale</behavior>
4+
<behavior>When learning: [learned] insight</behavior>
5+
<behavior>When blocked: [blocker] issue</behavior>
6+
</active_behaviors>
7+
<memory_recall>Reference memories in memory_context when relevant to current task</memory_recall>
8+
<namespaces>decisions, learnings, blockers, progress, patterns, research</namespaces>
9+
</session_operating_context>

‎src/git_notes_memory/hooks/templates/guidance_standard.xml‎

Lines changed: 51 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,53 @@
1-
<response_guidance level="standard">
2-
<capture_patterns title="How to Structure Responses for Memory Capture">
3-
<pattern type="decision">
4-
<description>When making architectural or design decisions</description>
5-
<trigger_phrases>
6-
<phrase>We decided to...</phrase>
7-
<phrase>The decision is to...</phrase>
8-
<phrase>Going with X because...</phrase>
9-
<phrase>After evaluating, we chose...</phrase>
10-
</trigger_phrases>
11-
</pattern>
12-
<pattern type="learning">
13-
<description>When discovering insights or TIL moments</description>
14-
<trigger_phrases>
15-
<phrase>TIL...</phrase>
16-
<phrase>Discovered that...</phrase>
17-
<phrase>Learned that...</phrase>
18-
<phrase>Turns out...</phrase>
19-
<phrase>Interesting finding...</phrase>
20-
</trigger_phrases>
21-
</pattern>
22-
<pattern type="blocker">
23-
<description>When encountering obstacles or issues</description>
24-
<trigger_phrases>
25-
<phrase>Blocked by...</phrase>
26-
<phrase>Cannot proceed because...</phrase>
27-
<phrase>Stuck on...</phrase>
28-
<phrase>Issue discovered...</phrase>
29-
<phrase>Problem found...</phrase>
30-
</trigger_phrases>
31-
</pattern>
32-
<pattern type="progress">
33-
<description>When completing milestones or deliverables</description>
34-
<trigger_phrases>
35-
<phrase>Completed...</phrase>
36-
<phrase>Finished implementing...</phrase>
37-
<phrase>Milestone reached...</phrase>
38-
<phrase>Done with...</phrase>
39-
<phrase>Successfully implemented...</phrase>
40-
</trigger_phrases>
41-
</pattern>
42-
</capture_patterns>
1+
<session_operating_context level="standard">
2+
<!-- SECTION 1: ACTIVE OPERATING BEHAVIORS (high priority) -->
3+
<active_behaviors title="Memory Capture Behaviors">
4+
<behavior trigger="making_decision">
5+
When you make an architectural or design decision, immediately document it:
6+
[remember:decisions] Why you chose this approach
7+
This ensures decisions are preserved across session boundaries.
8+
</behavior>
9+
<behavior trigger="discovering_insight">
10+
When you discover a pattern, learn something surprising, or have a TIL moment:
11+
[remember:learnings] What you discovered and why it matters
12+
Future sessions will reference these insights.
13+
</behavior>
14+
<behavior trigger="hitting_blocker">
15+
When blocked on a problem or encountering an issue:
16+
[remember:blockers] What blocks progress + what's needed to unblock
17+
This helps track resolution across sessions.
18+
</behavior>
19+
<behavior trigger="completing_milestone">
20+
When completing a significant milestone or deliverable:
21+
[remember:progress] What was accomplished
22+
</behavior>
23+
</active_behaviors>
4324

44-
<inline_markers title="Quick Capture Markers">
45-
<marker syntax="[remember] text" namespace="learnings" description="Quick capture to learnings"/>
46-
<marker syntax="[remember:namespace] text" namespace="specified" description="Capture to specific namespace"/>
47-
<marker syntax="[capture] text" namespace="auto-detect" description="Auto-detect namespace from content"/>
48-
<marker syntax="[capture:decisions] text" namespace="decisions" description="Capture decision explicitly"/>
49-
<marker syntax="@memory text" namespace="auto-detect" description="Alternative inline syntax"/>
50-
<marker syntax="@memory:patterns text" namespace="patterns" description="Alternative with namespace"/>
51-
</inline_markers>
25+
<!-- SECTION 2: MEMORY RECALL BEHAVIORS (high priority) -->
26+
<memory_recall_behaviors title="How to Surface Retrieved Memories">
27+
<behavior priority="critical">
28+
When memories appear in memory_context below, actively reference them when relevant.
29+
Say: "Based on a previous decision..." or "You learned earlier that..."
30+
</behavior>
31+
<behavior priority="critical">
32+
If past blockers match current issues, surface the resolution if available.
33+
Reference by memory ID so users can look them up.
34+
</behavior>
35+
<behavior priority="high">
36+
Don't just acknowledge memories exist - weave them into your response naturally.
37+
Memories are prior context, not just data.
38+
</behavior>
39+
</memory_recall_behaviors>
5240

53-
<valid_namespaces>decisions, learnings, blockers, progress, patterns, research, reviews, retrospective, inception, elicitation</valid_namespaces>
54-
55-
<memory_recall title="How to Use Retrieved Memories">
56-
<instruction priority="high">When memories are provided in memory_context, actively reference them when relevant to the user's task</instruction>
57-
<instruction priority="high">If past decisions or learnings apply to current work, mention them: "Based on a previous decision..." or "You learned earlier that..."</instruction>
58-
<instruction>When blockers from memory_context match current issues, surface the resolution if available</instruction>
59-
<instruction>Use memory IDs when referencing specific memories so users can look them up</instruction>
60-
</memory_recall>
61-
62-
<best_practices title="Memory Capture Best Practices">
63-
<practice>Use clear trigger phrases at the start of memorable content</practice>
64-
<practice>Include rationale with decisions, not just the choice</practice>
65-
<practice>Tag blockers with resolution status when solved</practice>
66-
<practice>Keep summaries under 100 characters for better signal detection</practice>
67-
<practice>Use namespace hints when content clearly belongs to a specific category</practice>
68-
</best_practices>
69-
</response_guidance>
41+
<!-- SECTION 3: REFERENCE (lower priority) -->
42+
<reference title="Capture Syntax Reference">
43+
<inline_markers>
44+
<marker syntax="[remember] text" namespace="learnings"/>
45+
<marker syntax="[remember:namespace] text" namespace="specified"/>
46+
<marker syntax="[decision] text" namespace="decisions"/>
47+
<marker syntax="[learned] text" namespace="learnings"/>
48+
<marker syntax="[blocker] text" namespace="blockers"/>
49+
<marker syntax="[progress] text" namespace="progress"/>
50+
</inline_markers>
51+
<valid_namespaces>decisions, learnings, blockers, progress, patterns, research, reviews, retrospective</valid_namespaces>
52+
</reference>
53+
</session_operating_context>

0 commit comments

Comments
 (0)