From agent-almanac
Runs a structured observation session: frames a target, witnesses with sustained attention, records patterns, categorizes findings, generates hypotheses, and archives a pattern library. Use when a system's behavior is unclear, debugging an unknown root cause, or auditing reasoning for biases.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:observeThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Conduct a structured observation session — framing the observation target, witnessing with sustained neutral attention, recording patterns without interpretation, categorizing findings, generating hypotheses from patterns, and archiving the observations for future reference.
Conduct a structured observation session — framing the observation target, witnessing with sustained neutral attention, recording patterns without interpretation, categorizing findings, generating hypotheses from patterns, and archiving the observations for future reference.
learn has built a model that needs validation through observation of the system in actionDefine what is being observed, why, and from what perspective.
Observation Protocol by System Type:
┌──────────────────┬──────────────────────────┬──────────────────────────┐
│ System Type │ What to Observe │ Categories to Watch │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Codebase │ File structure, naming │ Patterns, anti-patterns, │
│ │ conventions, dependency │ consistency, dead code, │
│ │ flow, test coverage, │ documentation quality, │
│ │ error handling patterns │ coupling between modules │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ User behavior │ Question patterns, │ Expertise signals, pain │
│ │ vocabulary evolution, │ points, unstated needs, │
│ │ repeated requests, │ learning trajectory, │
│ │ emotional signals │ communication style │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Tool / API │ Response patterns, error │ Rate limits, edge cases, │
│ │ conditions, latency, │ undocumented behavior, │
│ │ output format variations │ state dependencies │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ Own reasoning │ Decision patterns, tool │ Biases, habits, blind │
│ │ selection habits, error │ spots, strengths, │
│ │ recovery approaches, │ recurring failure modes, │
│ │ communication patterns │ over/under-confidence │
└──────────────────┴──────────────────────────┴──────────────────────────┘
Expected: A clear frame that directs attention without constraining it. The observer knows where to look and what categories to sort observations into, but remains open to the unexpected.
On failure: If the observation target is too broad ("observe everything"), narrow to one subsystem or one behavior pattern. If the target is too narrow ("observe this one variable"), zoom out to the surrounding context — the interesting patterns are often at the edges.
Hold attention on the observation target without interpreting, judging, or intervening.
Expected: A collection of raw observations — specific, concrete, and free from interpretation. Observations read like field notes: "File X imports Y but does not use function Z. File A has 300 lines; file B has 30 lines and covers similar functionality."
On failure: If observation immediately triggers analysis ("this is wrong because..."), the analytical habit is overriding the observational stance. Consciously separate the phases: write the observation as a fact, then write the interpretation as a separate note labeled "hypothesis." If neutrality is impossible (strong reaction to what is observed), note the reaction itself as data: "I noticed strong concern when observing X — this may indicate a significant issue or may indicate my bias."
Transcribe observations into a structured format while they are fresh.
Expected: A structured record of 5-15 discrete observations, each with specific evidence. The record should be detailed enough that another observer could verify each observation independently.
On failure: If observations are too abstract ("the code seems messy"), they need grounding in specifics — which files, which patterns, what makes it messy? If observations are too granular ("line 47 has a space before the brace"), zoom out to the pattern level — is this a one-off or a systemic issue?
Sort observations into meaningful categories without yet explaining them.
Expected: A categorized observation map with clear groupings. Each category has specific observations supporting it. The map shows both patterns and gaps.
On failure: If categorization feels forced, the observations may not have natural groupings — they may be a collection of unrelated findings, which is itself a finding (the system may lack coherent structure). If everything fits neatly into one category, the observation scope was too narrow — zoom out.
Now — and only now — begin interpreting the observations.
Expected: 2-4 hypotheses that explain the major patterns, each supported by specific observations. At least one hypothesis should be surprising or contrarian. The distinction between observation and interpretation is maintained — it is clear which parts are data and which are theory.
On failure: If no hypotheses form, the observations may need more time to accumulate — return to Step 2. If too many hypotheses form (everything is "maybe"), select the 2-3 with the strongest evidence and set the rest aside. If only obvious hypotheses form, force a contrarian view: "What if the opposite were true?"
Preserve the observations and hypotheses for future reference.
Expected: An archive that future observation sessions can build on. The archive distinguishes clearly between observations (data) and hypotheses (interpretation). It is honest about confidence levels and gaps.
On failure: If the observations do not feel worth archiving, they may have been too shallow — or they may be genuinely routine (not every observation session produces insights). Archive even negative results: "Observed X and found no anomalies" is useful future context.
observe-guidance — the human-guidance variant for coaching a person in systematic observationlearn — observation feeds learning by providing raw data for model-buildinglisten — outward-focused attention toward user signals; observation is broader-scope attention toward any systemremote-viewing — intuitive exploration that can be validated through systematic observationmeditate — develops the sustained attention capacity that observation requiresawareness — threat-focused situational awareness; observation is curiosity-driven rather than defense-drivennpx claudepluginhub pjt222/agent-almanacGuides systematic observation of systems or phenomena for debugging, research, or evidence-based reporting. Helps frame targets, take field notes, recognize patterns, and form hypotheses.
Applies disciplined observation to suspend interpretation and see what's actually there before deciding what it means. Useful for careful analysis of situations.
Runs focused observation sessions to analyze specific codebase patterns like error handling, naming conventions, or directories. Records findings for future /learn runs.