Observer — パッシブプロジェクトインテリジェンス

プロジェクト知識を時間をかけて蓄積する非干渉的な観察システムです。決定事項を記録し、パターンを発見し、ドリフトにフラグを立て、生きた知識ドキュメントを合成します。アクティブな作業を中断することはありません。

オブザーバーは自動的に実行されることはありません。呼び出したときのみ動作します。

ストレージ: デフォルトでは data/observations.jsonl にあるファイルベースの JSONL です。より豊富なバックエンド(例：SQLite キャンペーンDB)を持つリポジトリは、project.toml の [observer].backend を設定してバックエンド固有のコマンドを使用できます。

呼び出し

ユーザーコマンド

/observe note <category> <summary>      # 観察を記録する
/observe review                          # コンテキストをスキャンし、観察を提案する
/observe list [--category X] [--status X]  # 観察をクエリする
/observe resolve <id> [--detail "..."]   # 観察を解決済みにマークする
/observe stale [--days 14]               # 古い観察を自動的に陳腐化させる
/observe scan [--auto]                   # プローブを実行し、閾値観察を発行する
/observe synthesize                      # project-intelligence.md を更新する
/observe status                          # 観察の数を表示する
/observe cycle [--auto]                  # 複合: scan → stale → synthesize

エージェントコマンド

これらのコマンドはマシン処理用の構造化JSON出力を生成します。エージェントおよび他のスキルはこれらを専用に使用すべきです。

/observe briefing --format json          # エージェント用プロジェクト状態スナップショット
/observe check --format json             # プリフライトゲート (合格/不合格)
/observe list --format json              # 観察をJSON配列としてクエリする
/observe note ... --format json          # 記録し、確認JSON を返す
/observe scan --auto --format json       # スキャンして結果をJSON として返す
/observe cycle --auto --format json      # 完全なサイクル、サマリー JSON を返す

観察スキーマ

すべての観察には以下のフィールドがあります:

フィールド	タイプ	デフォルト	注記
`ts`	ISO 8601 タイムスタンプ	現在	記録時刻
`cat`	文字列	必須	カテゴリ(下記参照)
`summary`	文字列	必須	1 行の説明
`detail`	文字列	`""`	拡張コンテキスト
`files`	文字列[]	`[]`	関連ファイルパス
`plan`	文字列	`null`	リンク済みプラン ID
`agent`	文字列	`null`	リンク済みエージェント ID
`confidence`	浮動小数点数	`0.5`	確実性 (0.0–1.0)
`status`	文字列	`"open"`	`open`、`resolved`、または `stale`
`severity`	文字列	`"info"`	`info`、`warning`、または `critical`
`actor`	文字列	`"observer"`	記録者
`resolved_at`	タイムスタンプ	`null`	解決時刻
`resolved_detail`	文字列	`null`	解決メモ

重要度レベル:

レベル	意味	使用時機
`info`	ルーチン検出	手動ノートとパターンのデフォルト
`warning`	注意が必要	ドリフト、緩い閾値超過、増加する技術債
`critical`	進捗をブロック	ビルド失敗、違反、リグレッション

フィードバック優先順位付け

以下のシグナルの記録を優先してください:

ユーザーの明示的な修正
具体的な出力を伴う失敗した検証コマンド
繰り返されるワークアラウンドまたは繰り返されるレビュアー検出結果
次のエージェントがどのように計画・検証すべきかを変更するドリフト

証拠に基づいており、将来の行動を変える可能性が高い場合を除き、1 回限りの弱いシグナルを耐久性のあるプロジェクトメモリに変えないでください。

出力コントラクト

すべてのコマンドはマシン可読出力用に --format json をサポートします。--format json が渡されると、コマンドは stdout に単一の JSON オブジェクトのみを出力します — 前置きなし、マークダウンなし、解説なし。

Note 出力

{
  "action": "note",
  "recorded": true,
  "observation": {
    "ts": "2026-03-21T14:30:00Z",
    "cat": "risk",
    "summary": "no tests for payment module",
    "severity": "warning",
    "status": "open",
    "confidence": 0.5
  }
}

重複排除された場合 (スキップ):

{
  "action": "note",
  "recorded": false,
  "reason": "duplicate",
  "existing": {"cat": "risk", "summary": "no tests for payment module"}
}

List 出力

{
  "action": "list",
  "count": 3,
  "filters": {"category": "risk", "status": "open"},
  "observations": [
    {"ts": "2026-03-21T09:15:00Z", "cat": "risk", "summary": "no tests for payment module", "severity": "warning", "status": "open", "confidence": 0.8, "files": ["src/payment.py"]},
    {"ts": "2026-03-21T14:30:00Z", "cat": "risk", "summary": "API keys in env without rotation", "severity": "critical", "status": "open", "confidence": 0.9, "files": []}
  ]
}

Status 出力

{
  "action": "status",
  "total": 23,
  "by_status": {"open": 18, "resolved": 3, "stale": 2},
  "by_severity": {"info": 18, "warning": 4, "critical": 1},
  "by_category": {
    "decision": {"open": 3, "resolved": 1, "stale": 1},
    "risk": {"open": 3, "resolved": 1, "stale": 0}
  },
  "last_observation": "2026-03-21T14:30:00Z",
  "last_synthesis": "2026-03-20T10:00:00Z",
  "metrics_tracked": 3
}

Scan 出力

{
  "action": "scan",
  "probes_run": 5,
  "metrics_updated": [
    {"key": "dirty_file_count", "value": 5, "previous": 3, "delta": 2},
    {"key": "todo_count", "value": 42, "previous": 38, "delta": 4}
  ],
  "observations_emitted": [
    {"cat": "drift", "summary": "TODO count increased by 4 (now 42)", "severity": "warning", "recorded": true}
  ],
  "observations_resolved": [
    {"cat": "risk", "summary": "dirty file count above threshold", "reason": "metric recovered"}
  ]
}

Briefing 出力

{
  "action": "briefing",
  "status": "warning",
  "health": "degraded",
  "summary": "2 warnings, 0 critical — 15 open observations",
  "critical": [],
  "warnings": [
    {"cat": "risk", "summary": "no tests for payment module", "files": ["src/payment.py"]},
    {"cat": "drift", "summary": "auth module untouched for 3 weeks", "files": ["src/auth/"]}
  ],
  "metrics": {
    "dirty_file_count": 3,
    "todo_count": 42,
    "plans_executing": 1
  },
  "open_count": 15,
  "next_actions": [
    "Add test coverage for payment module",
    "Review auth module for staleness"
  ]
}

health の値: healthy (重大度 0、警告 0)、degraded (警告のみ)、 unhealthy (重大度あり)。

Check 出力

{
  "action": "check",
  "gate": "pass",
  "blockers": [],
  "warnings": ["no tests for payment module"],
  "open_critical": 0,
  "open_blockers": 0,
  "open_regressions": 0
}

終了コード: gate=pass の場合 0、gate=fail の場合 1。

Cycle 出力

{
  "action": "cycle",
  "scan": {"probes_run": 5, "metrics_updated": 3, "observations_emitted": 1},
  "stale": {"marked": 2},
  "synthesize": {"file": "docs/observer/project-intelligence.md", "sections": 9},
  "status": {"total": 23, "open": 16, "critical": 0, "warning": 3}
}

Resolve 出力

{
  "action": "resolve",
  "id": "2026-03-21T09:15:00Z:risk:no tests for payment module",
  "status": "resolved",
  "resolved_at": "2026-03-22T10:00:00Z",
  "resolved_detail": "Added pytest coverage in test_payment.py"
}

コマンド

`/observe note <category> <summary>`

単一の観察を記録します。重複排除: 同一の開いている観察がすでに存在する場合(同じカテゴリ+サマリー)は静かにスキップします。

カテゴリは以下のいずれかである必要があります:

カテゴリ	何をキャプチャするか
`decision`	行われたアーキテクチャまたは設計選択
`pattern`	繰り返されるコードまたはワークフローパターン
`drift`	計画からの乖離または注意のバランス不足
`risk`	発見された潜在的な問題
`progress`	マイルストーンと完了
`question`	未解決の設計質問
`debt`	蓄積する技術債

実行スコープカテゴリ(/observe-test で使用、マージ後昇格):

カテゴリ	何をキャプチャするか
`test-pass`	テストスイート成功と数
`test-fail`	根本原因を伴うテスト失敗
`build-error`	コンパイルまたはリンク失敗
`regression`	以前のパスしたテストが今は失敗
`churn`	ファイルが 3 回以上編集 (設計の不安定性)
`blocker`	エージェントが進行不可 — 依存関係欠落
`workaround`	エージェントが進行するために使用したハック

すべてのカテゴリは同じ観察ストアに書き込まれ、/observe synthesize 出力に表示されます。

オプションフラグ:

--detail "longer explanation" — 拡張コンテキスト
--files "file1.c,file2.h" — 関連ファイル (カンマ区切り)
--plan-id <plan-id> — キャンペーンプランへのリンク
--agent-id <agent-id> — キャンペーンエージェントへのリンク
--confidence 0.8 — 確実性レベル (0.0–1.0、デフォルト 0.5)
--severity warning — デフォルト info レベルをオーバーライド
--actor <name> — 記録者 (デフォルト: observer)
--format json — テキストの代わりに JSON 確認を返す

記録方法 (JSONL バックエンド):

現在のタイムスタンプを取得:
```
date -u +"%Y-%m-%dT%H:%M:%SZ"
```
重複をチェック — 同じ cat+summary の開いている観察が存在する場合はスキップ:
```
grep -c '"cat":"decision","summary":"chose JSONL"' data/observations.jsonl 2>/dev/null
```

JSON 観察オブジェクトを構築:

{"ts":"2026-03-21T14:30:00Z","cat":"decision","summary":"chose JSONL over SQLite for portability","status":"open","severity":"info","detail":"...","files":["src/storage.py"],"plan":null,"agent":null,"confidence":0.5,"actor":"observer"}

data/observations.jsonl に追加:

echo '{"ts":"...","cat":"...","summary":"...","status":"open","severity":"info"}' >> data/observations.jsonl

--format json の場合、Note 出力コントラクトを出力 (出力コントラクトを参照)。

`/observe list [--category X] [--status X] [--since DATE] [--format json]`

オプションのフィルタで観察をクエリします。

パイプライン:

data/observations.jsonl からすべての観察を読み込む
フィルタを適用:
- --category risk — risk 観察のみ表示
- --status open — open 観察のみ表示
- --since 2026-03-15 — この日付以降の観察を表示
- --severity critical — critical 観察のみ表示
フォーマット済みテーブルとして出力 (デフォルト) または List 出力コントラクト (--format json)

人間向け出力:

#  Timestamp             Cat       Sev      Status  Summary
1  2026-03-20T10:00:00Z  decision  info     open    chose event sourcing for audit trail
3  2026-03-21T09:15:00Z  risk      warning  open    no tests for payment module
5  2026-03-21T14:30:00Z  drift     info     open    auth module untouched for 3 weeks

`/observe resolve <id> [--detail "resolution notes"]`

観察を解決済みにマークしながら、その履歴を保持します。

パイプライン:

data/observations.jsonl を読み込み、ID によって観察を検索 (行番号または一致するタイムスタンプ+カテゴリ+サマリー)
status を "resolved" に設定、resolved_at タイムスタンプを追加
--detail が指定されている場合、resolved_detail を設定
更新されたエントリで JSONL ファイルを再度書き込む
--format json の場合、Resolve 出力コントラクトを出力
それ以外の場合は観察サマリーで確認を印刷

`/observe stale [--days 14]`

N 日以上前の観察を自動的に陳腐化させます(デフォルト 14 日)。

パイプライン:

data/observations.jsonl からすべての開いている観察を読み込む
ts が --days 閾値より古い各開いている観察について:
- status を "stale" に設定
JSONL ファイルを再度書き込む
カウントを出力: "Marked N observations as stale"

`/observe scan [--auto] [--format json]`

プロジェクト状態に対してプローブを実行し、メトリクスを更新し、閾値観察を発行します。これは構造化プロジェクトヘルスデータを収集する主な方法です。

プローブ(すべて git/ファイルベース、ビルドツールチェーン依存なし):

プローブ	何をチェックするか	メトリクスキー
Git 状態	`git status --porcelain`経由のコミットされていないファイル	`dirty_file_count`
TODO マーカー	ソースファイル全体の `git grep -c 'TODO\|FIXME\|HACK\|XXX'`	`todo_count`
ファイルチャーン	`git log --name-only`経由で最後の 10 コミット内で 3 回以上変更されたファイル	(churn 観察を発行)
プラン状態	トラッカーファイルを解析して実行中/承認済みプラン数	`plans_executing`、`plans_approved`
最近のアクティビティ	`git log --oneline -10` でよどんだ領域を検出	(drift 観察を発行)

メトリクスストレージ: data/metrics.jsonl — 各行はゲージです:

{"key":"dirty_file_count","value":5,"previous":3,"unit":"files","ts":"2026-03-21T14:30:00Z"}

閾値駆動観察: メトリクスが閾値を超えると、自動的に観察を発行します:

メトリクス	閾値	重要度	観察
`dirty_file_count`	>= 10	warning	"N uncommitted files — possible merge risk"
`todo_count`	前回から > 10% 変化	warning	"TODO count changed by N (now M total)"
`plans_executing`	> 0 ただし最近のコミットなし	warning	"Plan executing but no activity in N days"

自動解決: メトリクスが閾値以下に回復すると、一致する開いている観察を自動的に解決します。

--auto フラグ: 閾値駆動観察についてユーザー確認をスキップします。--auto なしでは、提案されるすべての観察は次のステップに進む前に承認が必要です。

--format json: Scan 出力コントラクトを返す (出力コントラクトを参照)。

消費者拡張ポイント: ビルドツールチェーンを備えたリポジトリは、バックエンド内のスキャンパイプラインを拡張することで dotnet build、cmake、テストランナー、エンフォースメントフック、等のプローブを追加できます。ポータブルスキルは git のみのプローブをカバーします。

`/observe review`

スキルレベルのワークフロー(バックエンドコマンドではなく)で、現在のプロジェクトコンテキストを読み込み、新しい観察を提案します。これは時間をかけて定性的な観察を構築するための主な方法です。

パイプライン:

data/observations.jsonl から既存の観察を読み込む:
```
cat data/observations.jsonl 2>/dev/null | wc -l
```
すでに記録されているものを理解するために JSON 行を解析します。
最近のコンテキストを読み込む:
- git log --oneline -20 — 最近のコミット
- git diff --stat HEAD~5 — 最近のファイル変更
- [paths].tracker からトラッカーファイルを読み込む — 現在のキャンペーン状態
- docs/observer/project-intelligence.md — 最後の合成 (存在する場合)
以下を分析:
- 決定 — 最近のコミットまたはセッションでなされた決定
- パターン — 一緒に変更されるファイル、繰り返されるエラータイプ
- ドリフト — 最近のアクティビティなしの領域 vs. アクティブな領域
- リスク — 欠落したテスト、増加する複雑さ、未解決の TODO
- 質問 — 最近の作業における曖昧さ、決定されていない設計選択
- 技術債 — TODO/FIXME/HACK コメント、ワークアラウンド
各候補観察について:
- 重複排除をチェック (同じカテゴリ+サマリーが開いている -> スキップ)
- 影響に基づいて重要度を割り当て (info/warning/critical)
- 承認をユーザーに提示
- 承認時に data/observations.jsonl への追加経由で記録
サマリー: 何個の新しい観察が記録されたか、カテゴリ分類

非干渉コントラクト:

review 中にユーザー承認なしに自動記録しない
コードまたはプランを変更しない
プロジェクト状態のみを読み込み、観察を提案

`/observe synthesize`

すべての観察を読み込み、docs/observer/project-intelligence.md にある生きた知識ドキュメントを生成します。

パイプライン:

data/observations.jsonl からすべての観察を読み込む:
```
cat data/observations.jsonl
```
テーマごとにクラスタ:
- カテゴリごとにグループ化
- カテゴリ内、関連ファイルまたはトピックでクラスタ
- 頻出数をカウント (類似の観察=より強いシグナル)
セクションとともに docs/observer/project-intelligence.md を書き込む:
- Active Themes — 頻度別のトップパターン、信頼度でソート (最大 5 個)
- Decisions Log — カテゴリ: decision、逆時系列
- Drift & Risks — 未解決の drift + risk 観察、重要度でソート
- Emerging Patterns — カテゴリ: pattern、発生回数とともに
- Test & Build Observations — ワークツリーから昇格された実行スコープカテゴリ
- Open Questions — カテゴリ: question、未解決
- Technical Debt — カテゴリ: debt、未解決
- Recently Resolved — タイムスタンプ付きの最後の 10 個の解決済み観察
- Stats — カテゴリとステータス別のカウントテーブル
メモリへのコンパクトサマリーを保存:
- ファイル: プロジェクトメモリ observer_summary.md
- コンテンツ: トップ 3 テーマ、未解決のリスク数、開いている質問数
- 目的: 将来のセッションでパッシブコンテキストのため自動読み込み

`/observe status [--format json]`

カテゴリ、ステータス、重要度別に観察数を表示します。

人間向け出力:

Observations: 23 total (18 open, 3 resolved, 2 stale)
Severity: 1 critical, 4 warning, 18 info

  decision:  5 (3 open)
  pattern:   4 (4 open)
  drift:     3 (2 open, 1 stale)
  risk:      4 (3 open, 1 resolved)
  progress:  3 (2 open, 1 resolved)
  question:  2 (2 open)
  debt:      2 (2 open, 1 stale)

Last observation: 2026-03-21
Last synthesis:   2026-03-20
Metrics: 3 tracked (dirty_file_count, todo_count, plans_executing)

--format json: Status 出力コントラクトを返す (出力コントラクトを参照)。

`/observe briefing [--format json]`

エージェント向けプロジェクト状態スナップショット。人間が読むためではなく、他のスキルとエージェントによる消費用に設計されたコンパクトなサマリーを返します。

パイプライン:

開いている観察、ストレージから現在のメトリクスを読み込む
全体的なステータスを決定:
- critical — 重大度 critical の開いている観察が存在
- warning — 重要度 warning の開いている観察が存在
- ok — info 重要度の観察のみ
ヘルスを決定: healthy (重大度 0、警告 0)、degraded (警告)、 unhealthy (重大度あり)
開いている critical/warning 観察から next_actions を構築
Briefing 出力コントラクトを出力 (出力コントラクトを参照)

使用者: /discover (研究前コンテキスト)、/planner (計画前のリスクチェック)、 /manager (エージェント起動前のプリフライト)、任意のエージェント (セッション開始時のコンテキスト)。

`/observe check [--format json]`

エージェント用プリフライトゲート。終了コード 0 (クリア) または 1 (ブロック) を返します。

パイプライン:

開いている観察を読み込む
ブロッカーをチェック:
- 重大度 critical の開いている観察がある -> 終了 1
- カテゴリ blocker の開いている観察がある -> 終了 1
- カテゴリ regression の開いている観察がある -> 終了 1
Check 出力コントラクトを返す (出力コントラクトを参照)

終了コード: gate=pass の場合 0、gate=fail の場合 1。

使用者: /manager run (起動前チェック)、/manager verify (マージ準備ゲート)。

`/observe cycle [--auto] [--format json]`

1 回の呼び出しで完全な観察サイクルを実行する複合コマンド。

パイプライン:

Scan — すべてのプローブを実行、閾値観察を発行

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

observer

SKILL.md 本文

Observer — パッシブプロジェクトインテリジェンス

呼び出し

ユーザーコマンド

エージェントコマンド

観察スキーマ

フィードバック優先順位付け

出力コントラクト

Note 出力

List 出力

Status 出力

Scan 出力

Briefing 出力

Check 出力

Cycle 出力

Resolve 出力

コマンド

`/observe note <category> <summary>`

`/observe list [--category X] [--status X] [--since DATE] [--format json]`

`/observe resolve <id> [--detail "resolution notes"]`

`/observe stale [--days 14]`

`/observe scan [--auto] [--format json]`

`/observe review`

`/observe synthesize`

`/observe status [--format json]`

`/observe briefing [--format json]`

`/observe check [--format json]`

`/observe cycle [--auto] [--format json]`

詳細情報