j5ik2o-takt-analyzer

TAKT Analyzer

Analyze existing TAKT workflows and facets, detect issues, and provide improvement suggestions.

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/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 events	references/takt/src/core/logging/usageEventLogger.ts	Structure of usage amount events
span→NDJSON mapper	references/takt/src/core/logging/span-to-ndjson-mapper.ts	Structure of OTel span-derived shadow session log (v0.44.0~)
Phase usage events	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/generate files
Input	Workflow YAML + facet + Execution logs	Same as left
Judgment	Severity classification of issues	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 destinations	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 paths actually exist	Critical
parallel structure	Whether the parent ruleall()/any()uses, and in substepsnextis missing	Warning
edit=false + build operations	edit: false Instructions for the steps of are build commands (cargo check etc.) explicitly prohibits. In a read-only sandbox, builds fail with Operation not permitted and fail with	Warning
Transition destination for supervise failure	supervise Whether the failure rule for plan has not transitioned to . Fixable issues should transition to fix should transition to, andsupervise → plan only when a fundamental design change is required	Warning
Responsibility allocation for CI execution	supervise/ai_review etc., edit: false Whether the instructions for steps such as prohibit direct CI execution andfix/implement only require confirmation of report evidence for	Warning
command quality gate	quality_gates の type: command is placed only in the agent step, and on the config side, workflow_command_gates.custom_scripts: true is enabled	Warning
provider_options structure	allowed_tools is not at the top level provider_options.claude.allowed_tools Is it placed in (v0.30.0~)	Warning
provider_options.$ref deprecated	provider_options.$ref Is it not used (v0.47.0~).extends Migration to is required	Warning
provider_routing migration	persona_providers Is it not used (deprecated as of v0.47.0).provider_routing（personas/tags/steps axis) should be used	Warning
edit permission	edit: trueappropriate for the steprequired_permission_modeis present	Info
session settings	For implementation stepssession: refreshis present	Info

2. Facet quality analysis

Check whether each facet complies with the style guide.

Persona check:

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

Policy check:

• Purpose explanation is one sentence
• A principles table exists
• There is no knowledge specific to a particular agent
• Size: within 300 lines

Instruction check:

• Starts with an 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
• Review-related includes status and cognitive load reduction rules
• File names have no numeric prefix
• Size: within 30 lines

3. Facet separation analysis

Detect whether responsibilities between facets are appropriately separated.

Violation pattern	Description	Fix direction
Policy details in persona	Rules with code examples/tables are inside the persona	→ Move to policy
Workflow concepts in persona	Step names/report file names are in the persona	→ Move to instructions
Policy-specific knowledge	Agent-specific detection methods are in the policy	→ Move to persona domain knowledge
Principles in instructions	Shared coding principles are in the instructions	→ Move to policy
Procedures in output contract	Execution procedures are in the output contract	→ Move to instructions

4. Rule design analysis

Evaluate the design of rule conditions.

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

5. Built-in usage 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 the similarity is high, propose replacing with built-ins
3. Detect mixing of built-in bare name references and section map references

6. Log-based diagnostic analysis

Analyze execution logs (.takt/logs/*.jsonl) and detect dynamic issues. Skip if there are no logs.

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 onward,observability.enabled: true is a prerequisite):

• .takt/runs/<run>/monitor.json: workflow metrics per run (observability.monitor: true output)
• shadow session log derived from OTel spans (observability.session_log_exporter: true output). 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, v0.45.0 onward).PhaseUsageEventLogRecord NDJSON of type. Each phase (phase1_execute / phase2_report / phase3_structured / phase3_tag / phase3_fallback) for each provider, provider_model, step, step_type, phase, usage record.npm run analyze:usage Can be aggregated with the following command

OTLP export (v0.46.0–,observability.enabled: true + OTEL_EXPORTER_OTLP_ENDPOINT is a prerequisite):

• observability.enabled: true and OTEL_EXPORTER_OTLP_ENDPOINT If the environment variable is set, TAKT sends spans and metrics via OTLP HTTP while keeping 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 span is nested under the parent workflow trace (detached trace prior to v0.46.0)
• A short-lived that makes running workflows easier to discover in Grafana Tempo, etc. Send a span ( workflow_start.<workflowName> span (takt.workflow.status = running has attributes. Not a replacement for root / step / phase / judge spans; discovery only)
• 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 including)
phase_start	Start of phase
phase_complete	Phase completion (error has field)
phase_judge_stage	Stage record of rule evaluation phase (stage, method, status including)
workflow_complete	Normal completion of workflow execution (iterations including)
workflow_abort	Interruption of workflow execution (reason including)
interactive_start / interactive_end	Start/end of interactive mode

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

b) matchedRuleMethod

step_complete record's matchedRuleMethod indicates by which method the rule evaluation engine matched 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	Determined by the completion status of parallel substeps
phase3_tag	None	High	Determined deterministically by tags in the output template
phase1_tag	None	Medium	Detect tags from agent responses
ai_judge	API 1 time	Medium	ai() AI judges only the conditions
ai_judge_fallback	API 1 time	Low	AI judges all conditions (when tag detection fails)
auto_select	None	High	Auto-selection when there is only one rule
structured_output	None	High	Judgment by structured output

ai_judge_fallback If the frequency of is high, a tag output instruction should be added to output-contract. step_start also includes providerOptions / providerOptionsSources for , 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 hotspot	Same step's step_start Aggregate the number of occurrences of	Exceeding threshold = Warning,loop_monitor Not set = Critical
Dead rule	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
Error 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, 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 workflow YAML to be analyzed 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. Validate YAML syntax
2. Check the step structure
3. Type-check rule conditions
4. Resolve section map references

Step 3: Load facets and quality check

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

Step 3.5: Load logs and diagnose (only when logs exist)

1. .takt/logs/latest.json Get the latest session ID from
2. Target's .jsonl Read the file, parse NDJSON records
3. Calculate each metric according to the Category 6 diagnostic analysis items
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（改善提案）
| # | カテゴリ | 場所 | 提案 |
|---|---------|------|------|

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

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