takt-analyze

TAKT Analyzer

Analyze existing TAKT pieces and facets, detect problems, and propose improvements.

Prerequisite takt version: v0.30.0

Reference materials

Material	Path	Purpose
YAML schema	references/takt/builtins/skill/references/yaml-schema.md	Validation criteria for piece structure
Engine specification	references/takt/builtins/skill/references/engine.md	Rule evaluation and execution specification
Style guides	references/takt/builtins/ja/*_STYLE_GUIDE.md	Facet quality criteria
Built-in pieces	references/takt/builtins/ja/pieces/	Reference for structural patterns
Built-in facets	references/takt/builtins/ja/{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
Rule evaluation	references/takt/src/core/piece/evaluation/RuleEvaluator.ts	How matchedRuleMethod works

Differences from takt-optimize

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

Analysis categories

1. Piece structure analysis

Detect structural problems in the piece YAML.

Check items:

Check	Content	Severity
initial_movement existence	initial_movementがmovementsWhether it exists in the array	Critical
Validity of transition destinations	Allrules.nextare valid movement names or COMPLETE/ABORTか	Critical
loop healthy transition consistency	loop_monitors.cycle healthy-time next whether it matches the cycle head node	Critical
loop reference report range	loop_monitors.judge.instruction_template の {report:...} whether it is only movement outputs within the cycle	Critical
Section map consistency	Whether the section map keys and references within movements match	Critical
File path existence	Whether the section map paths actually exist	Critical
parallel structure	Whether the parent rule usesall()/any(), and substeps havenextor not	Warning
edit=false + build operation	edit: false whether the instructions of the movement are build commands (cargo check Does it explicitly prohibit etc.? Builds fail in a read-only sandbox with Operation not permitted fails with	Warning
supervise failure transition destination	supervise Is the failure rule for plan not transitioning 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 Do instructions for movements such as edit: false prohibit direct execution of CI, andfix/implement require only confirmation of report evidence for	Warning
provider_options structure	allowed_tools が provider_options.claude.allowed_tools Is it placed in （v0.30.0〜）	Warning
edit permission	edit: trueappropriate for the movementrequired_permission_modeIs there	Info
session settings	For implementation-related movements,session: refreshIs there	Info

2. Facet quality analysis

Check whether each facet complies with the style guide.

Persona check:

• Role definition is 1-2 sentences
• Responsible agent names in “what to do” and “what not to do”
• Policy detailed rules (code examples, tables) are not mixed in
• No piece-specific concepts (movement names, etc.)
• Size: simple within 100 lines, expert within 550 lines
• ####The following nesting is absent

Policy check:

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

Instruction check:

• Begins with an imperative
• {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:

• ```markdownIs enclosed in a code block
• Status and cognitive load reduction rules for review-related items
• 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 in the persona	→ Move to policy
Piece concepts in persona	Movement names/report file names are in the persona	→ Move to instruction
Specific knowledge in policy	Agent-specific detection methods are in the policy	→ Move to persona domain knowledge
Principles in instruction	Shared coding principles are in the instructions	→ move to policy
Procedures are in the 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() 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	For each loop monitor, is the "healthy (has progress)" next the first node of the cycle
loop report consistency	Does the loop monitor reference a report dedicated to out-of-cycle movement
ABORT conditions	Are ABORT transitions on failure appropriately defined

5. Built-in utilization analysis

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

Steps:

1. Compare the contents of custom facets with built-in facets
2. If similarity is high, propose replacement with a built-in
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 problems. If there are no logs, skip.

a) Log location and format

• .takt/logs/{sessionId}.jsonl(NDJSON format: one JSON object per line)
• .takt/logs/latest.json refer to the latest session ID with

NDJSON record type list:

type	Content
piece_start	Start of piece execution
step_start	Start of movement (step)
step_complete	Movement completion (includesmatchedRuleIndex, matchedRuleMethod )
phase_start	Start of phase
phase_complete	Phase completion (haserror field)
piece_complete	Normal completion of piece execution (includesiterations )
piece_abort	Interruption of piece execution (includesreason )
interactive_start / interactive_end	Start/end of interactive mode

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

Logs in separate files (v0.30.0〜):

File	Format	Content	Settings
{sessionId}-provider-events.jsonl	NDJSON	Provider API events (token count, latency, etc.)	logging.provider_events: true
trace.md	Markdown	Execution trace report (phase/movement execution history)	logging.trace: true

These are output to a separate file from the session NDJSON. The configuration is controlled in the ~/.takt/config.yaml の logging section (renamed to observability → logging in v0.30.0).

b) matchedRuleMethod

step_complete For the matchedRuleMethod record, the

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	Tag detection from agent response
ai_judge	1 API call	Medium	ai() AI judgment only for
ai_judge_fallback	1 API call	Low	AI judgment for 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

c) Diagnostic analysis items

Analysis	Method	Severity criteria
Loop hotspots	For the same step, step_start aggregate the number of occurrences	Exceeding threshold = Warning,loop_monitor not set = Critical
Dead rules	matchedRuleIndex Detect rules with 0 matches based on the distribution of	Critical (unreachable code)
Rule evaluation efficiency	matchedRuleMethod Aggregate the distribution ofai_judge_fallback Focus on the proportion of	>50%=Warning、>80%=Critical
ABORT rate	piece_abort / piece_complete Ratio of	>30%=Warning、>50%=Critical
Errors by phase	phase_complete の error Aggregate the	Repeated errors in the same phase = Warning
Iteration efficiency	piece_complete.iterations vs max_movements	Always near the upper limit = Warning

d) Guide to integrated analysis of multiple logs

• 3 times or more: 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_movements exceeded"

Workflow

Step 1: Identify the target

Identify the piece YAML to be analyzed and check whether execution logs exist.

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

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

Step 2: Parse the piece YAML

Read the piece YAML and perform structural analysis.

1. Validation of YAML syntax
2. Check of movement composition
3. Type checking of rule conditions
4. Resolution of section map references

Step 3: Load facets and check quality

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

Step 3.5: Log loading and diagnostics (only when logs are present)

1. .takt/logs/latest.json Get the latest session ID from
2. Target .jsonl Load the file and parse the 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（改善提案）
| # | カテゴリ | 場所 | 提案 |
|---|---------|------|------|

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

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