takt-analyzer

TAKT Analyzer

Analyze existing TAKT workflows and facets, detect issues, and propose improvements.

Prerequisite takt version: v0.47.0

Reference materials

Material	Path	Purpose
YAML schema	references/takt/builtins/skill/references/yaml-schema.md	Workflow structure validation criteria
Engine specification	references/takt/builtins/skill/references/engine.md	Rule evaluation and execution specification
Style guide collection	references/takt/builtins/ja/*_STYLE_GUIDE.md	Facet quality criteria
Built-in workflow	references/takt/builtins/ja/workflows/	Reference for structural patterns
Built-in facet	references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/	Reference for facet quality
Log type definitions	references/takt/src/shared/utils/types.ts	Reference for NDJSON record types
Provider event	references/takt/src/core/logging/providerEventLogger.ts	*-provider-events.jsonl structure of
Usage event	references/takt/src/core/logging/usageEventLogger.ts	Structure of usage volume events
span→NDJSON mapper	references/takt/src/core/logging/span-to-ndjson-mapper.ts	Structure of OTel span-derived shadow session logs (v0.44.0~)
Phase usage event	references/takt/src/core/logging/phaseUsageEvent.ts	*-usage-events.phase.jsonl の PhaseUsageEventLogRecord type (v0.45.0~)
Rule evaluation	references/takt/src/core/workflow/evaluation/RuleEvaluator.ts	Mechanism of matchedRuleMethod (when: including deterministic conditions)
Trace discovery	references/takt/src/core/workflow/observability/traceDiscovery.ts	From OTel span WorkflowTraceDiscoveryModule that constructs (including task metadata) (v0.47.0~)

Differences from takt-optimize

Perspective	takt-analyze	takt-optimize
Purpose	Issue detection, diagnosis, and reporting	Execution of optimization
Output	Analysis report (Markdown)	Optimized file set
Changes	None (read-only)	Directly edit and generate files
Input	Workflow YAML + facet + Execution logs	Same as left
Judgment	Issue severity classification	Cost/quality trade-off judgment

Analysis categories

1. Workflow structure analysis

Detect structural issues in workflow YAML.

Check items:

Check	Content	Severity
initial_step existence	initial_stepがstepsWhether it exists in the array	Critical
Validity of transition targets	Allrules.nextis a valid step name or COMPLETE/ABORTか	Critical
loop healthy transition consistency	loop_monitors.cycle healthy-time next matches the first node of the cycle	Critical
loop reference report range	loop_monitors.judge.instruction の {report:...} is only step outputs within the cycle	Critical
Section map consistency	Whether section map keys and in-step references match	Critical
File path existence	Whether the section map path actually exists	Critical
parallel structure	Parent ruleall()/any()uses, and substeps have nonextis missing	Warning
edit=false + build operation	edit: false Whether the instructions for the step explicitly prohibit build commands (cargo check etc.). In a read-only sandbox, the build fails with Operation not permitted fails with	Warning
Transition destination for supervise failure	supervise Whether the failure rule for plan does not transition to fix Fixable issues should transition tosupervise → plan only when a fundamental design change is required	Warning
Responsibility placement for CI execution	supervise/ai_review etc., whether the instructions for the edit: false step prohibit direct CI execution andfix/implement only require confirmation of report evidence for	Warning
command quality gate	quality_gates の type: command is placed only on the agent step, and on the config side workflow_command_gates.custom_scripts: true is enabled	Warning
provider_options structure	allowed_tools is placed not at the top level but in provider_options.claude.allowed_tools (v0.30.0〜)	Warning
provider_options.$ref deprecated	provider_options.$ref is not used (v0.47.0〜).extends Migration to	Warning
provider_routing migration	persona_providers is not used (deprecated since v0.47.0).provider_routing（personas/tags/steps axis) should be used	Warning
edit permission	edit: trueappropriate for the steprequired_permission_modeexists	Info
session settings	For implementation steps,session: refreshexists	Info

2. Facet quality analysis

Check whether each facet complies with the style guide.

Persona check:

• Role definition is 1-2 sentences
• Responsible agent name in "what to do" and "what not to do"
• Detailed policy rules (code examples, tables) are not mixed in
• No workflow-specific concepts (step names, etc.)
• Size: simple within 100 lines, expert within 550 lines
• ####No nesting of the following

Policy check:

• Purpose description is 1 sentence
• Principles table exists
• No knowledge specific to a particular agent
• Size: within 300 lines

Instruction check:

• Begins with imperative form
• {task}, {previous_response}is not manually written
• Persona/policy content is not mixed in
• Size: within the upper limit according to type

Output Contract check:

• ```markdownEnclosed in a code block
• Status and cognitive load reduction rules in review-type
• No numeric prefix in filename
• Size: within 30 lines

3. Facet separation analysis

Detect whether responsibilities between facets are appropriately separated.

Violation pattern	Description	Correction direction
Policy details in persona	Rules with code examples/tables inside persona	→ Move to policy
Workflow concepts in persona	Step names/report filenames inside persona	→ Move to instructions
Specific knowledge in policy	Detection methods specific to a particular agent inside policy	→ Move to persona domain knowledge
Principles in instructions	Shared coding principles inside instructions	→ Move to policy
Procedures in output contract	Execution procedures inside output contract	→ Move to instructions

4. Rule design analysis

Evaluate the design of rule conditions.

Check	Content
Tags vs AI judgment	Is ai() used where tag-based conditions could handle it?
aggregate usage	Is all()/any() used in the parent of parallel?
Unreachable rules	Are there cases that do not match any condition?
Loop risk	Are there loop_monitors for cycles such as fix→review?
Loop healthy transition	In each loop monitor, is the "healthy (progress made)" next at the head node of the cycle?
Loop report consistency	Does a loop monitor reference a report dedicated to a step outside the cycle?
ABORT condition	Are ABORT transitions on failure appropriately defined?

5. Built-in utilization analysis

Detect whether custom facets can be replaced by built-ins.

Procedure:

1. Compare the contents of custom facets with built-in facets
2. If similarity is high, propose replacement with built-ins
3. Detect mixing of built-in bare name references and section map references

6. Log-based diagnostic analysis

Execution log (.takt/logs/*.jsonl) and detect dynamic problems. Skip if there is no log.

a) Log location and format

• .takt/logs/{sessionId}.jsonl(NDJSON format: one JSON object per line)
• .takt/logs/{sessionId}-provider-events.jsonl(provider event log, separate file)
• .takt/logs/{sessionId}/trace.md(trace report, Markdown format)
• .takt/logs/latest.json refer to the latest session ID with

observability opt-in output (v0.44.0~,observability.enabled: true is required):

• .takt/runs/<run>/monitor.json: run-level workflow metrics (observability.monitor: true output with)
• shadow session log derived from OTel spans (observability.session_log_exporter: true output with). The same redaction as the regular NDJSON session log is applied
• spans also cover phase execution and the status-judgment (judge) phase
• .takt/runs/<run>/logs/<session>-usage-events.phase.jsonl: phase-granularity provider usage events (observability.usage_events_phase: true output with, v0.45.0~).PhaseUsageEventLogRecord type NDJSON. For each phase (phase1_execute / phase2_report / phase3_structured / phase3_tag / phase3_fallback) record provider, provider_model, step, step_type, phase, usage .npm run analyze:usage can be aggregated with the command

OTLP export (v0.46.0~,observability.enabled: true + OTEL_EXPORTER_OTLP_ENDPOINT is required):

• observability.enabled: true and OTEL_EXPORTER_OTLP_ENDPOINT if the environment variable is set, TAKT sends spans and metrics over OTLP HTTP while maintaining the local exporter
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT individual endpoints can be overridden with (only effective when a base endpoint is set)
• To propagate the W3C trace context to each provider subprocess, the provider CLI's spans are nested under the parent workflow trace (before v0.46.0 they were detached traces)
• Send a short-lived workflow_start.<workflowName> span to make running workflows easier to discover with Grafana Tempo etc. (takt.workflow.status = running has attributes. Not a replacement for root / step / phase / judge spans, but dedicated to discovery)
• For details of the export implementation, see references/takt/docs/observability.ja.md see

NDJSON record type list:

type	Content
workflow_start	Start of workflow execution
step_start	Start of step
step_complete	Step completion (matchedRuleIndex, matchedRuleMethod included)
phase_start	Start of phase
phase_complete	Phase completion (error field present)
phase_judge_stage	Staged record of the rule judgment phase (stage, method, status included)
workflow_complete	Normal completion of workflow execution (iterations included)
workflow_abort	Interruption of workflow execution (reason included)
interactive_start / interactive_end	Start/end of interactive mode

For detailed fields of each record type, see references/takt/src/shared/utils/types.ts .

b) matchedRuleMethod

step_complete record's matchedRuleMethod indicates which method the rule evaluation engine used to match the rule.

Evaluation order (fallback chain):

1. aggregate     → all()/any() による並列サブステップ集約
2. phase3_tag    → Phase 3 出力からのタグ検出
3. phase1_tag    → Phase 1 出力からのタグ検出（フォールバック）
4. ai_judge      → ai() 条件のみをAI判定
5. ai_judge_fallback → 全条件をAI判定（最終フォールバック）

Characteristics by method:

method	Cost	Reliability	Description
aggregate	None	High	Judged by the completion status of parallel substeps
phase3_tag	None	High	Deterministically judged by tags in the output template
phase1_tag	None	Medium	Detect tags from agent response
ai_judge	1 API call	Medium	ai() AI judges only the conditions
ai_judge_fallback	1 API call	Low	AI judges all conditions (when tag detection fails)
auto_select	None	High	Automatic selection when there is only one rule
structured_output	None	High	Judgment via structured output

ai_judge_fallback If the frequency of is high, a tag output instruction should be added to output-contract. step_start also contains providerOptions / providerOptionsSources also contains, so it can be used to analyze the cause of provider / effort resolution differing from expectations.

c) Diagnostic analysis items

Analysis	Method	Severity criteria
Loop hotspots	Same step's step_start Count occurrences	Exceeding threshold = Warning,loop_monitor Not set = Critical
Dead rules	matchedRuleIndex Detect rules with 0 matches in the distribution of	Critical (unreachable code)
Rule evaluation efficiency	matchedRuleMethod Aggregate the distribution of .ai_judge_fallback Focus on the proportion of	>50%=Warning、>80%=Critical
ABORT rate	workflow_abort / workflow_complete Ratio of	>30%=Warning、>50%=Critical
Errors by phase	phase_complete の error Aggregate the field	Repeated errors in the same phase = Warning
Iteration efficiency	workflow_complete.iterations vs max_steps	Always near the upper limit = Warning

d) Guide for integrated analysis of multiple logs

• 3 or more times: Sufficient for pattern confirmation. Report statistical trends
• 1 time: Treat as reference information and prioritize static analysis

e) Example log diagnostic report

## ログ診断結果

### 分析対象
- セッション数: 5
- 期間: 2026-03-01 〜 2026-03-04

### ルール評価効率
| ステップ | phase3_tag | ai_judge | ai_judge_fallback | 改善優先度 |
|------------|-----------|---------|-------------------|----------|
| ai_review  | 20%       | 13%     | 67%               | 高       |
| supervise  | 80%       | 20%     | 0%                | -        |

### ループホットスポット
| サイクル | 最大連続回数 | loop_monitor | 状態 |
|---------|------------|-------------|------|
| review→fix | 6 | threshold: 3 | OK |
| implement→test | 4 | なし | Warning: loop_monitor未設定 |

### ABORT分析
- 成功: 4/5 (80%)
- ABORT: 1/5 (20%) - reason: "max_steps exceeded"

Workflow

Step 1: Identify the target

Identify the target workflow YAML for analysis and check whether execution logs exist.

探索順序:
1. ユーザー指定のパス
2. ~/.takt/workflows/ 内のカスタムワークフロー
3. .takt/workflows/ 内のプロジェクトワークフロー

ログ確認:
- .takt/logs/ ディレクトリの存在確認
- ログあり → 静的分析 + ログ診断
- ログなし → 静的分析のみ（従来通り）

Step 2: Workflow YAML analysis

Read the workflow YAML and perform structural analysis.

1. Validation of YAML syntax
2. Confirmation of step structure
3. Type checking of rule conditions
4. Resolution of section map references

Step 3: Facet loading and quality check

Load all facets from the section map and built-in references, and check them against the style guide.

Step 3.5: Log loading and diagnosis (only when logs exist)

1. .takt/logs/latest.json Get the latest session ID from
2. Target .jsonl Read the file and parse NDJSON records
3. Calculate each metric according to the diagnostic analysis items in Category 6
4. If there are multiple logs, perform integrated analysis

Step 4: Separation analysis

Detect responsibility violations between facets.

Step 5: Report output

# TAKT分析レポート: {ワークフロー名}

## サマリー
- Critical: {N件}
- Warning: {N件}
- Info: {N件}

## Critical（必須修正）
| # | カテゴリ | 場所 | 問題 |
|---|---------|------|------|

## Warning（推奨修正）
| # | カテゴリ | 場所 | 問題 | 改善案 |
|---|---------|------|------|--------|

## Info（改善提案）
| # | カテゴリ | 場所 | 提案 |
|---|---------|------|------|

## ビルトイン活用の提案
{カスタムファセットのビルトイン置き換え提案}

## ログ診断結果（ログ提供時のみ）
{ログベース診断のサマリー}