j5ik2o-takt-optimizer

TAKT Optimizer

Execute optimization of an existing TAKT workflow. Diagnosis and analysis are handled by takt-analyze.

Prerequisite takt version: v0.47.0

Reference materials

Material	Path	Purpose
YAML schema	references/takt/builtins/skill/references/yaml-schema.md	Validation criteria for workflow structure
Engine specification	references/takt/builtins/skill/references/engine.md	Understanding prompt construction and token consumption
Style guide groups	references/takt/builtins/ja/*_STYLE_GUIDE.md	Facet size limits
Built-in workflow	references/takt/builtins/ja/workflows/	Reference for optimization patterns
Built-in facet	references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/	Built-in replacement candidates

Differences from takt-analyze

Perspective	takt-analyze	takt-optimize
Purpose	Problem detection, diagnosis, and reporting	Execution of optimization
Output	Analysis report (Markdown)	Optimized file groups
Changes	None (read-only)	Directly edit and generate files
Input	Workflow YAML + facets + execution logs	Workflow YAML + facet + Diagnostic results from takt-analyze
Judgment	Problem severity classification	Cost/quality trade-off judgment
Log analysis	Execute it yourself and generate a diagnostic report	Use the diagnostic results from takt-analyze

Recommended flow: takt-analyze(Diagnosis) → Based on the results, takt-optimize(optimization execution)

Optimization categories

1. Token consumption reduction

Reduce the token volume during prompt construction.

Engine prompt construction order (see: engine.md):

ペルソナ → ポリシー → コンテキスト → ナレッジ → インストラクション
→ タスク → 前回出力 → レポート指示 → タグ指示 → ポリシーリマインダー

Note: The policy is injected twice, at the beginning and at the end (as a countermeasure against Lost in the Middle). Bloated policies double token consumption.

Optimization	Method	Effect
Persona compression	Removing redundant descriptions, compressing to within the size limit	Reduction at each step
Policy splitting	Split a huge policy by purpose and assign it only to the necessary steps	Double effect (for the reminder portion)
Knowledge narrowing	Remove knowledge references unnecessary for the step	Reduction of unnecessary context
Instruction simplification	Remove manual descriptions of automatically injected content	Deduplication
Output contract slimming	Compress output contracts over 30 lines	Reduce in the report instruction section

Facet size guideline:

Facet	Recommended	Upper limit
Persona (simple)	30-50 lines	100 lines
Persona (expert)	50-300 lines	550 lines
Policy	60-250 lines	300 lines
Instruction (review)	5-12 lines	-
Instruction (plan/fix)	10-20 lines	-
Instruction (implement)	30-50 lines	-
Output Contract	10-25 lines	30 lines

2. Step integration

Integrate unnecessary steps to reduce the total number of steps in the workflow.

Pattern	Detection condition	Optimization
Consecutive identical personas	Adjacent steps have the same persona	Integrate into 1 step
Single-rule transition	One rule with an unconditional transition	Consider integration with preceding/following steps
edit=false chain	Chain of read-only steps	Evaluate integration possibility

Integration criteria:

• Whether personas are the same or different between steps
• Whether the session: refresh boundary is not broken
• Whether independence of report output is required
• Whether rule branching is substantially meaningful

3. Rule simplification

Optimize rule conditions.

Optimization	Before	After
ai() → tag replacement	ai("実装が完了した")	"実装完了" (tag-based)
Remove unreachable rules	One of the 3 conditions is unreachable	Delete the unreachable rule
Shorten condition text	"全てのレビュアーが承認した"	"approved"

ai() vs tag-based decision:

• Tag-based (recommended): When results can be clearly classified
• ai(): Only when context understanding is required for the judgment

4. Facet reuse

Replace custom facets with built-ins and reduce the section map.

Procedure:

1. List custom facets in the section map
2. Read the contents of each custom facet
3. Compare with built-in facets and evaluate similarity
4. If replaceable, replace with a bare name reference

Built-in replacement example:

# Before: カスタムファセットをセクションマップで参照
personas:
  my-coder: ../personas/my-coder.md
steps:
  - name: implement
    persona: my-coder

# After: ビルトインのbare name参照
steps:
  - name: implement
    persona: coder    # ビルトインを直接参照

Conditions under which replacement is not possible:

• Personas containing domain knowledge not present in built-ins
• Policies containing project-specific judgment criteria
• Instructions containing proprietary procedures

5. Loop control improvement

Improve the efficiency and safety of the correction loop.

Optimization	Content
Add loop_monitors	Add when there is no loop_monitor in the review→fix cycle
Adjust threshold	Suggest an appropriate value when the threshold is too high/too low
Add ABORT condition	Add when there is no ABORT transition on failure
max_steps adjustment	Adjust when max_steps is too large/too small relative to the number of steps
Fix supervise failure transitions	supervise On failure, plan change the rule that transitions to fix tosupervise → plan Loops tend to be costly and unproductive
Add edit=false build prohibition	edit: false Add a prohibition section ("do not execute build commands") to the instructions referenced by the## やらないこと) to the instructions referenced by the step
Normalize loop monitor judge instructions	loop_monitors.judge.instruction Unifyloop-monitor-ai-antipattern-fix, loop-monitor-reviewers-fix) and remove the old judge template notation
Migrate allowed_tools to provider_options	Top-level allowed_tools を provider_options.claude.allowed_tools (v0.30.0〜)
Organize command quality gates	Separate string gates and type: command gates, and limit command gates to agent steps. Delete unnecessary command gates, and if necessary, check the permission settings on the config side
Migrate provider_options.$ref → extends	In the workflow, provider_options.$ref: provider-options/edit.yaml を provider_options.extends: edit (v0.47.0〜 BREAKING: old $ref is invalid)
Migrate persona_providers → provider_routing	In the workflow, persona_providers: and migrate to the project/global setting provider_routing.personas(or provider_routing.tags/provider_routing.steps) (v0.47.0〜 deprecated)

threshold recommended values:

• review→fix cycle: 3 times
• supervise→fix cycle: 3 times
• implement→test cycle: 2 times

6. Parallelization proposal

Detect steps that are executed sequentially but can be parallelized.

Parallelization conditions:

• Do not reference each other's output (pass_previous_response not needed)
• Use the report from the same previous step as input
• Output independent reports

# Before: 逐次レビュー
- name: arch-review
  ...
  rules:
    - condition: done
      next: qa-review
- name: qa-review
  ...

# After: 並列レビュー
- name: reviewers
  parallel:
    - name: arch-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
    - name: qa-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
  rules:
    - condition: all("approved")
      next: supervise
    - condition: any("needs_fix")
      next: fix

7. Optimization based on log diagnosis results

Using the log diagnosis results from takt-analyze as input, perform optimization based on actual data.

Premise: Reading, analyzing, and diagnosing logs is handled by takt-analyze. In this category, only "what to change" is handled based on the diagnosis results.

Available log sources:

Log file	Granularity	Purpose
logs/<session>.jsonl	step unit	Loop detection, rule evaluation efficiency, ABORT rate
logs/<session>-provider-events.jsonl	provider call unit	Token consumption of each call
logs/<session>-usage-events.phase.jsonl	phase unit (v0.45.0〜)	Token consumption of step × phase × provider.observability.usage_events_phase: true Output withnpm run analyze:usage Can be aggregated with
OTLP span / metric（v0.46.0〜）	span / metric unit	OTEL_EXPORTER_OTLP_ENDPOINT Sent to Grafana Tempo etc. at configuration time. Because provider spans are nested within the workflow trace, the correspondence between steps and provider calls can be checked in the trace view

Diagnosis results → Optimization actions:

takt-analyze diagnosis	Optimization action
Loop hotspot (Warning/Critical)	loop_monitor の threshold adjustment, review of rule conditions
Dead rule (Critical)	Removal of unreachable rules
Rule evaluation efficiency is low (ai_judge_fallback high frequency)	Rewrite to tag-based rules, add tag output instructions to output-contract
ABORT rate is high	Flow improvement according to the reason of the ABORT cause (max_steps adjustment, addition of ABORT conditions)
Repeated errors by phase	Improvement of instructions and personas for phases with frequent errors
Iteration efficiency is low	max_steps Calculation of appropriate values for , consideration of step integration

Workflow

Step 1: Identifying and loading the target

Identify the target workflow YAML and load all related facets.

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

What to load:

• The entire workflow YAML
• All facet files of the section map
• Built-in facets (for comparison)
• takt-analyze diagnosis report (if provided)

Step 2: Creating an optimization plan

Evaluate the optimization potential of each category and present a plan.

# 最適化プラン: {ワークフロー名}

## 分析ソース
- 静的分析: ワークフローYAML + ファセット{N}件
- takt-analyze診断: {診断レポートの要約}（提供された場合）

## 推定効果
- トークン削減: 約{N}%
- ステップ数: {before} → {after}
- ファイル数: {before} → {after}

## 最適化項目
| # | カテゴリ | 対象 | 内容 | 根拠 | リスク |
|---|---------|------|------|------|--------|
| 1 | トークン削減 | persona/coder | 120行→80行に圧縮 | 静的 | 低 |
| 2 | ビルトイン置換 | persona/my-reviewer | → architecture-reviewer | 静的 | 低 |
| 3 | ルール簡素化 | ai_review | ai_fallback 67% → タグ化 | 診断 | 低 |
| 4 | 並列化 | arch-review + qa-review | 逐次→並列 | 静的 | 中 |

Confirm with the user: Present the plan and obtain approval for the items to execute.

Decision flow:

• 0 optimization items → report "Already sufficiently optimized" and end
• User approves some → execute only the approved items in Step 3
• User rejects all → end

Step 3: Executing optimization

Execute the approved items.

Execution order (in dependency order):

1. Facet compression/integration (changes to file contents)
2. Built-in replacement (changes to the section map)
3. Step integration (changes to the YAML structure)
4. Rule simplification (changes to rule conditions)
5. Loop control improvement (adding loop_monitors)
6. Parallelization (major changes to the step structure)

Step 4: Consistency verification

Check the consistency of the file group after optimization.

• The section map keys and in-step references match
• The section map paths point to files that actually exist
• initial_stepがstepsexists in the array
• For all rules, thenextis a valid transition destination
• The parallel parent ruleall()/any()uses
• In the rule of a parallel substep,nextthere is no
• Facets are within the size limit
• No references to deleted facets remain

Step 5: Result report

# 最適化結果: {ワークフロー名}

## サマリー
- トークン削減: 約{N}%（推定）
- ステップ数: {before} → {after}
- ファイル数: {before} → {after}

## 変更一覧
| # | ファイル | 変更内容 |
|---|---------|---------|
| 1 | workflows/my-workflow.yaml | ステップ統合、ルール簡素化 |
| 2 | personas/coder.md | 120行→80行に圧縮 |
| 3 | (削除) personas/my-reviewer.md | ビルトインに置換 |

## 削除ファイル
- personas/my-reviewer.md（→ ビルトイン architecture-reviewer で代替）

## 注意事項
{最適化による動作変更の可能性がある場合に記載}

Validation

Created/edited files can be mechanically verified with validate-takt-files.sh :

bash .agents/skills/takt-optimize/scripts/validate-takt-files.sh

Verification items:

• Workflow YAML: Required fields (name/initial_step/steps）、initial_step step references, existence of facet file references
• Facet .md: Empty check, persona/policy/knowledge require # 見出し , instruction/output-contract require content presence

Option --workflows / --facets can be used to narrow down the targets.