repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

skills: ai skill von isp aktualisiert

7e35df4b7ade2a6046544b45dc24cbe3095e00d6

Oliver Krylow <o.krylow@isp-insoft.de> ·

unsigned

Browse filesCompare with HEAD

Changed files (17)

Notes

Modified
1 -Subproject commit 9e81882dfb2915097d82af26608157dffdd6c3e9
1 +Subproject commit 938edd930387b55c988f99be0248ba5bea2baeb9

pi-ext

Modified
1 -Subproject commit 32af3873d77df3b2252c1da0d1cd81d419a4ae08
1 +Subproject commit 31526e9c2dca87e3a910d3a4db648280a6dddf30

pi/agent/settings.json

Modified

pi/agent/skills/.isp-skills.json

Modified
2 2 "experimentation": "4377b7dd6180967d47b1011aafd7d117129d46562388dce5778d0467679da200",
3 - "fxdriver": "60c5e9369ec272bfe2d3bff932e458bb5bfb2edd4a27de3f121d71a8cae4c473",
3 + "fxdriver": "e0886ac9c2b149233b28925e92e711967c850194a0b4137521f0c35371bbce49",
4 4 "fxdriver-instructions": "03acd906bfa49e7feef159191988e105505c9b5a6a1f80d7e48f1b2cf587665f",
5 - "isp-start-day": "40a4f931f9766d2327af8e79c5b68e3696aea74421bd980e850a68cf04f41481",
6 - "desloppy": "7ffcbcfc3b414477eb6825b625b647045e43653e53d412f844d6973de0f44acc"
5 + "isp-start-day": "36e3ed2f300e58b365b7a25bd21d8914f066d17735b188c7cd479172ecda82f4",
6 + "desloppy": "0df4ab44f58e464958d3d576533d2d5cf66359986c8175d45c5c4b2541fe13bc"

pi/agent/skills/desloppy/references/legacy-overengineering.md

Modified
1 -# Legacy and backwards-compatibility overengineering
3 -Agents tend to read the current codebase into context. When they then receive instructions for new code, old code and new instructions are not always weighed correctly.
5 -To weigh them correctly, the agent needs awareness about the state of the project and code.
7 -## What to look for
9 -Look for code or proposals that add or preserve complexity for reasons such as:
11 -- legacy behavior
12 -- backwards compatibility
13 -- migrations
14 -- versioning
16 -These concerns may be important, or they may be useless noise, depending on the lifecycle stage of the project.
18 -## Project and code state matters
20 -In production, mission-critical, important, or released code, the old code may be very important. New code needs to take it into account.
22 -In new features, prototypes, or unreleased projects, things like backwards compatibility, migrations, and versioning may be too early in the lifecycle and become useless noise.
24 -## What the agent should verify
26 -Before preserving or removing compatibility complexity, verify the state of the project and code:
28 -- Is this production or mission-critical code?
29 -- Is this released code?
30 -- Is the behavior part of an external contract?
31 -- Is this a new feature, prototype, or unreleased project?
33 -## Pseudo-code examples
35 -### Suspicious in an unreleased prototype
37 -```text
38 -if request version is 1:
39 - use old prototype behavior
40 -else if request version is 2:
41 - use current prototype behavior
42 -else:
43 - use fallback behavior
44 -```
46 -If the project is unreleased or still a prototype, versioning and backwards compatibility may be useless noise.
48 -### Important in released production code
50 -```text
51 -if request version is 1:
52 - preserve released behavior
53 -else if request version is 2:
54 - use current behavior
55 -```
57 -In released production code, old behavior may be important and new code must take it into account.
59 -### Bad agent behavior: weighing old code blindly
61 -```text
62 -existing code has migration path
63 -new feature copies migration path
64 -```
66 -This may be wrong if the new feature is unreleased and does not need migrations yet.
68 -### Bad agent behavior: ignoring old code blindly
70 -```text
71 -new implementation replaces released behavior
72 -old compatibility path removed without checking project state
73 -```
75 -This may be wrong if the code is production, mission-critical, important, or released.
1 +# Legacy and backwards-compatibility overengineering
3 +Agents tend to read the current codebase into context. When they then receive instructions for new code, old code and new instructions are not always weighed correctly.
5 +To weigh them correctly, the agent needs awareness about the state of the project and code.
7 +## What to look for
9 +Look for code or proposals that add or preserve complexity for reasons such as:
11 +- legacy behavior
12 +- backwards compatibility
13 +- migrations
14 +- versioning
16 +These concerns may be important, or they may be useless noise, depending on the lifecycle stage of the project.
18 +## Project and code state matters
20 +In production, mission-critical, important, or released code, the old code may be very important. New code needs to take it into account.
22 +In new features, prototypes, or unreleased projects, things like backwards compatibility, migrations, and versioning may be too early in the lifecycle and become useless noise.
24 +## What the agent should verify
26 +Before preserving or removing compatibility complexity, verify the state of the project and code:
28 +- Is this production or mission-critical code?
29 +- Is this released code?
30 +- Is the behavior part of an external contract?
31 +- Is this a new feature, prototype, or unreleased project?
33 +## Pseudo-code examples
35 +### Suspicious in an unreleased prototype
37 +```text
38 +if request version is 1:
39 + use old prototype behavior
40 +else if request version is 2:
41 + use current prototype behavior
42 +else:
43 + use fallback behavior
44 +```
46 +If the project is unreleased or still a prototype, versioning and backwards compatibility may be useless noise.
48 +### Important in released production code
50 +```text
51 +if request version is 1:
52 + preserve released behavior
53 +else if request version is 2:
54 + use current behavior
55 +```
57 +In released production code, old behavior may be important and new code must take it into account.
59 +### Bad agent behavior: weighing old code blindly
61 +```text
62 +existing code has migration path
63 +new feature copies migration path
64 +```
66 +This may be wrong if the new feature is unreleased and does not need migrations yet.
68 +### Bad agent behavior: ignoring old code blindly
70 +```text
71 +new implementation replaces released behavior
72 +old compatibility path removed without checking project state
73 +```
75 +This may be wrong if the code is production, mission-critical, important, or released.

pi/agent/skills/desloppy/references/magic-values.md

Modified
1 -# Magic values
3 -Magic values are scalar literal values in code where it is not immediately apparent why they have their current value.
5 -They are called magic because they often encode an assumption or a relationship to other values that happens to be correct at the time.
7 -## What to look for
9 -Look for scalar literal values whose meaning, origin, unit, or relationship to other values is unclear.
11 -A common example is UI layout code:
13 -```text
14 -control.padding = 8
15 -```
17 -The value `8` may only look correct because another margin or spacing somewhere else happens to be `4`. If the relationship is “padding is twice the spacing”, the code should express that relationship instead of using a magic value.
19 -## Why it matters
21 -Magic values hide assumptions.
23 -They can also be duplicated in multiple places and drift over time when one occurrence changes but another related occurrence does not.
25 -## Preferred fix
27 -When the value represents a relationship, encode the relationship directly.
29 -When the relationship or context cannot be encoded, use a well-named constant.
31 -Sometimes magic values are unavoidable because the context is not understood or the context exists outside the code. In those cases, a well-named constant is still better than an unexplained literal.
33 -## When not to extract
35 -Many literal values technically fit the definition of a magic value but are accepted in programmer culture.
37 -For example, the zero index in a `for` loop is technically a scalar literal whose value matters, but there is no benefit in extracting it to a constant because every reader knows the pattern.
39 -Extracting such values can make code worse. A shared constant for a loop start index could even introduce a bug if changing the constant changes all starting indices at once.
41 -## Pseudo-code examples
43 -### Bad: hidden relationship
45 -```text
46 -spacing = 4
47 -control.padding = 8
48 -```
50 -The `8` only makes sense because it is related to `spacing`.
52 -### Better: express the relationship
54 -```text
55 -spacing = 4
56 -control.padding = 2 * spacing
57 -```
59 -This makes the assumption visible.
61 -### Acceptable fallback: well-named constant
63 -```text
64 -minimum_visible_items = 7
66 -if item_count < minimum_visible_items:
67 - show compact layout
68 -```
70 -If the context cannot be fully expressed in code, use a well-named constant.
72 -### Bad extraction: culturally understood value
74 -```text
75 -first_index = 0
77 -for index from first_index to item_count:
78 - process item[index]
79 -```
81 -This adds no benefit over the standard loop pattern.
83 -### Worse: shared constant that can create drift or bugs
85 -```text
86 -start_index = 0
88 -for index from start_index to item_count:
89 - process item[index]
91 -for retry from start_index to retry_count:
92 - attempt retry[retry]
93 -```
95 -Changing `start_index` would affect unrelated loops at once.
1 +# Magic values
3 +Magic values are scalar literal values in code where it is not immediately apparent why they have their current value.
5 +They are called magic because they often encode an assumption or a relationship to other values that happens to be correct at the time.
7 +## What to look for
9 +Look for scalar literal values whose meaning, origin, unit, or relationship to other values is unclear.
11 +A common example is UI layout code:
13 +```text
14 +control.padding = 8
15 +```
17 +The value `8` may only look correct because another margin or spacing somewhere else happens to be `4`. If the relationship is “padding is twice the spacing”, the code should express that relationship instead of using a magic value.
19 +## Why it matters
21 +Magic values hide assumptions.
23 +They can also be duplicated in multiple places and drift over time when one occurrence changes but another related occurrence does not.
25 +## Preferred fix
27 +When the value represents a relationship, encode the relationship directly.
29 +When the relationship or context cannot be encoded, use a well-named constant.
31 +Sometimes magic values are unavoidable because the context is not understood or the context exists outside the code. In those cases, a well-named constant is still better than an unexplained literal.
33 +## When not to extract
35 +Many literal values technically fit the definition of a magic value but are accepted in programmer culture.
37 +For example, the zero index in a `for` loop is technically a scalar literal whose value matters, but there is no benefit in extracting it to a constant because every reader knows the pattern.
39 +Extracting such values can make code worse. A shared constant for a loop start index could even introduce a bug if changing the constant changes all starting indices at once.
41 +## Pseudo-code examples
43 +### Bad: hidden relationship
45 +```text
46 +spacing = 4
47 +control.padding = 8
48 +```
50 +The `8` only makes sense because it is related to `spacing`.
52 +### Better: express the relationship
54 +```text
55 +spacing = 4
56 +control.padding = 2 * spacing
57 +```
59 +This makes the assumption visible.
61 +### Acceptable fallback: well-named constant
63 +```text
64 +minimum_visible_items = 7
66 +if item_count < minimum_visible_items:
67 + show compact layout
68 +```
70 +If the context cannot be fully expressed in code, use a well-named constant.
72 +### Bad extraction: culturally understood value
74 +```text
75 +first_index = 0
77 +for index from first_index to item_count:
78 + process item[index]
79 +```
81 +This adds no benefit over the standard loop pattern.
83 +### Worse: shared constant that can create drift or bugs
85 +```text
86 +start_index = 0
88 +for index from start_index to item_count:
89 + process item[index]
91 +for retry from start_index to retry_count:
92 + attempt retry[retry]
93 +```
95 +Changing `start_index` would affect unrelated loops at once.

pi/agent/skills/desloppy/references/missing-types-docs.md

Modified
1 -# Missing types and docs
3 -Missing types and missing docs are language- and project-dependent slop signals.
5 -Follow project rules first.
7 -## Missing or weak types
9 -Missing types are mainly a problem in languages with some form of gradual typing, such as:
11 -- TypeScript / JavaScript
12 -- typed Python
13 -- Teal / Lua
15 -In those languages, well-typed code should be preferred.
17 -In languages with stricter type systems, types cannot really be missing, but they can still be too general or too specific.
19 -## Type specificity
21 -In compiled languages, the general consensus is:
23 -- use general types for parameters and declarations
24 -- use specific types for values
26 -## Missing docs or comments
28 -For documentation, follow project rules in general.
30 -Complex, surprising, or side-effect-heavy code almost always deserves a comment or doccomment.
32 -## Good comments
34 -Good comments explain:
36 -- context
37 -- reason
38 -- motivation
40 -They explain why the code exists or why it is shaped this way.
42 -## Bad comments
44 -Never simply translate what the code does into human language.
46 -A comment that only restates the code is noise.
48 -## Pseudo-code examples
50 -### Bad: weak typing in gradually typed code
52 -```text
53 -function resize(value):
54 - return value * 2
55 -```
57 -In a gradually typed language, the input and output expectations are unclear.
59 -### Better: well-typed gradually typed code
61 -```text
62 -function resize(value: Pixels) -> Pixels:
63 - return value * 2
64 -```
66 -Well-typed code should be preferred in languages that support gradual typing.
68 -### Bad: comment only repeats the code
70 -```text
71 -# Add one to retry_count.
72 -retry_count = retry_count + 1
73 -```
75 -This only translates the code into human language.
77 -### Better: comment explains reason or context
79 -```text
80 -# The first retry happens immediately because the remote cache often becomes
81 -# visible one tick after the write succeeds.
82 -retry_count = retry_count + 1
83 -```
85 -This explains the reason and context.
87 -### Worth documenting: surprising side effect
89 -```text
90 -function calculate_total(order):
91 - # Also marks expired discounts as used because the billing system expects
92 - # discount state to be finalized during total calculation.
93 - expire_old_discounts(order)
94 - return sum order lines
95 -```
97 -Complex, surprising, or side-effect-heavy code almost always deserves a comment or doccomment.
1 +# Missing types and docs
3 +Missing types and missing docs are language- and project-dependent slop signals.
5 +Follow project rules first.
7 +## Missing or weak types
9 +Missing types are mainly a problem in languages with some form of gradual typing, such as:
11 +- TypeScript / JavaScript
12 +- typed Python
13 +- Teal / Lua
15 +In those languages, well-typed code should be preferred.
17 +In languages with stricter type systems, types cannot really be missing, but they can still be too general or too specific.
19 +## Type specificity
21 +In compiled languages, the general consensus is:
23 +- use general types for parameters and declarations
24 +- use specific types for values
26 +## Missing docs or comments
28 +For documentation, follow project rules in general.
30 +Complex, surprising, or side-effect-heavy code almost always deserves a comment or doccomment.
32 +## Good comments
34 +Good comments explain:
36 +- context
37 +- reason
38 +- motivation
40 +They explain why the code exists or why it is shaped this way.
42 +## Bad comments
44 +Never simply translate what the code does into human language.
46 +A comment that only restates the code is noise.
48 +## Pseudo-code examples
50 +### Bad: weak typing in gradually typed code
52 +```text
53 +function resize(value):
54 + return value * 2
55 +```
57 +In a gradually typed language, the input and output expectations are unclear.
59 +### Better: well-typed gradually typed code
61 +```text
62 +function resize(value: Pixels) -> Pixels:
63 + return value * 2
64 +```
66 +Well-typed code should be preferred in languages that support gradual typing.
68 +### Bad: comment only repeats the code
70 +```text
71 +# Add one to retry_count.
72 +retry_count = retry_count + 1
73 +```
75 +This only translates the code into human language.
77 +### Better: comment explains reason or context
79 +```text
80 +# The first retry happens immediately because the remote cache often becomes
81 +# visible one tick after the write succeeds.
82 +retry_count = retry_count + 1
83 +```
85 +This explains the reason and context.
87 +### Worth documenting: surprising side effect
89 +```text
90 +function calculate_total(order):
91 + # Also marks expired discounts as used because the billing system expects
92 + # discount state to be finalized during total calculation.
93 + expire_old_discounts(order)
94 + return sum order lines
95 +```
97 +Complex, surprising, or side-effect-heavy code almost always deserves a comment or doccomment.

pi/agent/skills/desloppy/references/overengineered-error-handling.md

Modified
1 -# Overengineered error handling
3 -Overengineered error handling relates to deep nesting, but it deserves its own reference because many languages have diverse and different error handling strategies.
5 -## What to look for
7 -Overengineered error handling includes error handling constructs that are:
9 -- misused for control flow
10 -- deeply nested
11 -- reliant on side effects
13 -## Why it matters
15 -Error handling can make code harder to understand when it obscures the normal behavior of the code or turns exceptional paths into the main control structure.
17 -## Pseudo-code examples
19 -### Bad: error handling used as control flow
21 -```text
22 -try:
23 - value = get cached value
24 -catch missing_value_error:
25 - value = calculate value
26 -```
28 -The missing cache value is part of normal control flow, but it is expressed as an error path.
30 -### Better: explicit control flow
32 -```text
33 -if cache has value:
34 - value = get cached value
35 -else:
36 - value = calculate value
37 -```
39 -Normal behavior is visible as normal control flow.
41 -### Bad: deeply nested error handling
43 -```text
44 -try:
45 - open resource
46 - try:
47 - read resource
48 - try:
49 - parse resource
50 - catch parse_error:
51 - handle parse error
52 - catch read_error:
53 - handle read error
54 -catch open_error:
55 - handle open error
56 -```
58 -The nesting makes the error behavior hard to read.
60 -### Better: flatter structure
62 -```text
63 -resource = open resource
64 -if open failed:
65 - handle open error
66 - return
68 -content = read resource
69 -if read failed:
70 - handle read error
71 - return
73 -parsed = parse content
74 -if parse failed:
75 - handle parse error
76 - return
77 -```
79 -Flattening can make the normal sequence and error cases easier to follow.
81 -### Bad: error handling reliant on side effects
83 -```text
84 -try:
85 - update account
86 -catch validation_error:
87 - validation_error handler also updates account state
88 - continue
89 -```
91 -The handler changes state in a way the reader may not expect.
93 -### Better: make side effects explicit
95 -```text
96 -validation = validate account update
97 -if validation failed:
98 - update account state for failed validation
99 - report validation error
100 - return
102 -update account
103 -```
105 -The side effect is visible in normal code instead of hidden inside error handling.
1 +# Overengineered error handling
3 +Overengineered error handling relates to deep nesting, but it deserves its own reference because many languages have diverse and different error handling strategies.
5 +## What to look for
7 +Overengineered error handling includes error handling constructs that are:
9 +- misused for control flow
10 +- deeply nested
11 +- reliant on side effects
13 +## Why it matters
15 +Error handling can make code harder to understand when it obscures the normal behavior of the code or turns exceptional paths into the main control structure.
17 +## Pseudo-code examples
19 +### Bad: error handling used as control flow
21 +```text
22 +try:
23 + value = get cached value
24 +catch missing_value_error:
25 + value = calculate value
26 +```
28 +The missing cache value is part of normal control flow, but it is expressed as an error path.
30 +### Better: explicit control flow
32 +```text
33 +if cache has value:
34 + value = get cached value
35 +else:
36 + value = calculate value
37 +```
39 +Normal behavior is visible as normal control flow.
41 +### Bad: deeply nested error handling
43 +```text
44 +try:
45 + open resource
46 + try:
47 + read resource
48 + try:
49 + parse resource
50 + catch parse_error:
51 + handle parse error
52 + catch read_error:
53 + handle read error
54 +catch open_error:
55 + handle open error
56 +```
58 +The nesting makes the error behavior hard to read.
60 +### Better: flatter structure
62 +```text
63 +resource = open resource
64 +if open failed:
65 + handle open error
66 + return
68 +content = read resource
69 +if read failed:
70 + handle read error
71 + return
73 +parsed = parse content
74 +if parse failed:
75 + handle parse error
76 + return
77 +```
79 +Flattening can make the normal sequence and error cases easier to follow.
81 +### Bad: error handling reliant on side effects
83 +```text
84 +try:
85 + update account
86 +catch validation_error:
87 + validation_error handler also updates account state
88 + continue
89 +```
91 +The handler changes state in a way the reader may not expect.
93 +### Better: make side effects explicit
95 +```text
96 +validation = validate account update
97 +if validation failed:
98 + update account state for failed validation
99 + report validation error
100 + return
102 +update account
103 +```
105 +The side effect is visible in normal code instead of hidden inside error handling.

pi/agent/skills/desloppy/references/poor-error-handling.md

Modified
1 -# Poor error handling
3 -Poor error handling can mean both handling too broadly and not handling broadly enough.
5 -## What to look for
7 -Poor error handling includes:
9 -- handling too broad a set of errors and reacting the same way to all of them
10 -- handling too narrow a set of errors and ignoring relevant error cases
12 -## Local or deferred handling
14 -Error handling may be local or deferred, depending on project rules.
16 -The important point is not where the error is handled, but that wherever it is handled, the handling itself is useful, actionable, and explains context to humans.
18 -## Who the error is for
20 -Some errors concern developers.
22 -Some errors concern end users.
24 -Depending on the case, different handling may be needed:
26 -- language
27 -- wording style
28 -- logging
29 -- quality of explanation
30 -- technical detail level
32 -## Error messages
34 -When crafting error messages, pay attention to:
36 -- context
37 -- technical details
38 -- localization
40 -## Pseudo-code examples
42 -### Bad: too broad, same reaction for everything
44 -```text
45 -try:
46 - load configuration
47 - connect to database
48 - read user input
49 -catch error:
50 - show "Something went wrong"
51 -```
53 -Different failures are collapsed into the same reaction, losing useful context.
55 -### Better: distinguish relevant cases
57 -```text
58 -try:
59 - load configuration
60 - connect to database
61 - read user input
62 -catch configuration_error:
63 - report developer-facing configuration context
64 -catch database_error:
65 - report connection context and useful technical details
66 -catch input_error:
67 - report user-facing input guidance
68 -```
70 -The handling gives humans useful and actionable context.
72 -### Bad: too narrow, error case ignored
74 -```text
75 -result = parse input
76 -use result
77 -```
79 -If parsing can fail, the error case is ignored.
81 -### Better: handle or defer according to project rules
83 -```text
84 -result = parse input
85 -if result is parse_error:
86 - handle here with useful context
87 - or return error with context for caller to handle
89 -use result
90 -```
92 -Handling can be local or deferred, but the eventual handling must be useful.
94 -### Developer-facing vs user-facing
96 -```text
97 -if migration file is invalid:
98 - log technical details for developers
99 - fail startup with configuration context
101 -if user entered invalid date:
102 - show localized user-facing guidance
103 -```
105 -Different audiences require different language, detail, logging, and wording style.
1 +# Poor error handling
3 +Poor error handling can mean both handling too broadly and not handling broadly enough.
5 +## What to look for
7 +Poor error handling includes:
9 +- handling too broad a set of errors and reacting the same way to all of them
10 +- handling too narrow a set of errors and ignoring relevant error cases
12 +## Local or deferred handling
14 +Error handling may be local or deferred, depending on project rules.
16 +The important point is not where the error is handled, but that wherever it is handled, the handling itself is useful, actionable, and explains context to humans.
18 +## Who the error is for
20 +Some errors concern developers.
22 +Some errors concern end users.
24 +Depending on the case, different handling may be needed:
26 +- language
27 +- wording style
28 +- logging
29 +- quality of explanation
30 +- technical detail level
32 +## Error messages
34 +When crafting error messages, pay attention to:
36 +- context
37 +- technical details
38 +- localization
40 +## Pseudo-code examples
42 +### Bad: too broad, same reaction for everything
44 +```text
45 +try:
46 + load configuration
47 + connect to database
48 + read user input
49 +catch error:
50 + show "Something went wrong"
51 +```
53 +Different failures are collapsed into the same reaction, losing useful context.
55 +### Better: distinguish relevant cases
57 +```text
58 +try:
59 + load configuration
60 + connect to database
61 + read user input
62 +catch configuration_error:
63 + report developer-facing configuration context
64 +catch database_error:
65 + report connection context and useful technical details
66 +catch input_error:
67 + report user-facing input guidance
68 +```
70 +The handling gives humans useful and actionable context.
72 +### Bad: too narrow, error case ignored
74 +```text
75 +result = parse input
76 +use result
77 +```
79 +If parsing can fail, the error case is ignored.
81 +### Better: handle or defer according to project rules
83 +```text
84 +result = parse input
85 +if result is parse_error:
86 + handle here with useful context
87 + or return error with context for caller to handle
89 +use result
90 +```
92 +Handling can be local or deferred, but the eventual handling must be useful.
94 +### Developer-facing vs user-facing
96 +```text
97 +if migration file is invalid:
98 + log technical details for developers
99 + fail startup with configuration context
101 +if user entered invalid date:
102 + show localized user-facing guidance
103 +```
105 +Different audiences require different language, detail, logging, and wording style.

pi/agent/skills/desloppy/references/single-use-functions.md

Modified
1 -# Single-use functions
3 -Single-use functions are often bad because they force names onto blocks of code.
5 -That can sometimes be a benefit, but only when the name is very good: short, descriptive, and unambiguous.
7 -## Why it matters
9 -Single-use functions force readers to jump and navigate around the codebase to understand behavior.
11 -In some languages, they can also incur performance or runtime costs.
13 -## When a single-use function can be good
15 -For complex or surprising code, giving the block a good name can be the right move.
17 -This only applies when the function name is very good:
19 -- short
20 -- descriptive
21 -- unambiguous
23 -More often than not, comments can serve the same purpose better.
25 -## Preferred fix
27 -Inline single-use functions when they do not justify the navigation cost.
29 -If the old function name was useful, translate it into a human-readable comment above the inlined code.
31 -## Tricky case: public functions
33 -Single-use public functions require careful analysis.
35 -They may be part of an API and only appear to be single-use from the current codebase.
37 -Analyze those cases case by case before proposing an inline.
39 -## Pseudo-code examples
41 -### Bad: single-use function with weak name
43 -```text
44 -function handle_request(request):
45 - prepare(request)
46 - send response
48 -function prepare(request):
49 - trim request fields
50 - default missing values
51 - normalize date format
52 -```
54 -The reader must jump to `prepare` to understand what actually happens.
56 -### Better: inline with a useful comment
58 -```text
59 -function handle_request(request):
60 - # Normalize request input before responding.
61 - trim request fields
62 - default missing values
63 - normalize date format
65 - send response
66 -```
68 -If the function name carried useful intent, convert that intent into a human-readable comment.
70 -### Acceptable: complex or surprising block with a very good name
72 -```text
73 -function handle_request(request):
74 - reject_if_signature_was_replayed(request)
75 - send response
77 -function reject_if_signature_was_replayed(request):
78 - complex or surprising replay-detection logic
79 -```
81 -A single-use function may be worth keeping when the code is complex or surprising and the name is short, descriptive, and unambiguous.
83 -### Risky: public single-use function
85 -```text
86 -public function normalize_request(request):
87 - trim request fields
88 - default missing values
89 - normalize date format
90 -```
92 -This may be an API even if it appears single-use inside the current codebase. Analyze case by case before proposing to inline it.
1 +# Single-use functions
3 +Single-use functions are often bad because they force names onto blocks of code.
5 +That can sometimes be a benefit, but only when the name is very good: short, descriptive, and unambiguous.
7 +## Why it matters
9 +Single-use functions force readers to jump and navigate around the codebase to understand behavior.
11 +In some languages, they can also incur performance or runtime costs.
13 +## When a single-use function can be good
15 +For complex or surprising code, giving the block a good name can be the right move.
17 +This only applies when the function name is very good:
19 +- short
20 +- descriptive
21 +- unambiguous
23 +More often than not, comments can serve the same purpose better.
25 +## Preferred fix
27 +Inline single-use functions when they do not justify the navigation cost.
29 +If the old function name was useful, translate it into a human-readable comment above the inlined code.
31 +## Tricky case: public functions
33 +Single-use public functions require careful analysis.
35 +They may be part of an API and only appear to be single-use from the current codebase.
37 +Analyze those cases case by case before proposing an inline.
39 +## Pseudo-code examples
41 +### Bad: single-use function with weak name
43 +```text
44 +function handle_request(request):
45 + prepare(request)
46 + send response
48 +function prepare(request):
49 + trim request fields
50 + default missing values
51 + normalize date format
52 +```
54 +The reader must jump to `prepare` to understand what actually happens.
56 +### Better: inline with a useful comment
58 +```text
59 +function handle_request(request):
60 + # Normalize request input before responding.
61 + trim request fields
62 + default missing values
63 + normalize date format
65 + send response
66 +```
68 +If the function name carried useful intent, convert that intent into a human-readable comment.
70 +### Acceptable: complex or surprising block with a very good name
72 +```text
73 +function handle_request(request):
74 + reject_if_signature_was_replayed(request)
75 + send response
77 +function reject_if_signature_was_replayed(request):
78 + complex or surprising replay-detection logic
79 +```
81 +A single-use function may be worth keeping when the code is complex or surprising and the name is short, descriptive, and unambiguous.
83 +### Risky: public single-use function
85 +```text
86 +public function normalize_request(request):
87 + trim request fields
88 + default missing values
89 + normalize date format
90 +```
92 +This may be an API even if it appears single-use inside the current codebase. Analyze case by case before proposing to inline it.

pi/agent/skills/fxdriver/SKILL.md

Modified
2 2 name: fxdriver
3 -description:
4 - "Drive JavaFX desktop apps through fxdriver JSON-RPC: attach to a running JVM,
5 - inspect snapshots, choose selectors, click/type/wait/assert, capture
6 - screenshots, and debug UI flows. Use when testing or automating JavaFX apps
7 - with fxdriver."
3 +description: "Drive and inspect JavaFX apps through fxdriver JSON-RPC. Use for JavaFX UI automation, assertions, screenshots, and debugging."
8 4 license: MIT
9 -compatibility:
10 - "fxdriver 0.1.0-SNAPSHOT. Requires JDK 21+."
5 +compatibility: "fxdriver 0.1.0-SNAPSHOT. Requires JDK 21+."
13 8 # fxdriver
15 -Use fxdriver as a low-level JavaFX driver. It observes public JavaFX UI state
16 -and performs requested actions. You decide test policy, assertions, visual
17 -quality judgments, and app-specific workflows.
10 +Drive JavaFX UI only; native dialogs and OS/global input need another tool.
19 -## Core loop
12 +## Loop
21 -1. Ensure target JavaFX app is running.
22 -2. Attach fxdriver to its JVM PID.
23 -3. Snapshot UI.
24 -4. Pick stable selectors (`nodeId`, `textExact`, `type`, `role`, `eid`).
25 -5. Act: `click`/`fire` buttons, `setText`/`type` fields, `setValue` or
26 - `selectIndex` for choice/range/table/tree controls, `fireMenuItem` for menus,
27 - and `key` for real keystrokes (Enter/Tab/chords).
28 -6. Wait/assert.
29 -7. Capture screenshot when uncertain or after visual changes; use
30 - `videoStart`/`videoStep`/`videoStop` to record a whole run as GIF or APNG
31 - with a stable canvas and native step titles.
32 -8. Use events/logs to explain failures.
14 +1. Start with `launch` or attach to a PID.
15 +2. Call `capabilities`, then `snapshot --summary`; use full `snapshot` only when needed.
16 +3. Prefer `nodeId`, then `textExact`, `eid`, role, or text. `selectorPath` is diagnostic, never a selector.
17 +4. Act with the control-specific method: `fire`/`click`, `setText`/`type`, `setValue`, `selectIndex`, `fireMenuItem`, `tableCell`, or `key`.
18 +5. `wait`/`assert` the result. Capture and read screenshots for visual claims.
19 +6. Save `events` on failure; call `shutdown`—launched apps exit, attached apps stay running.
34 -## Required references
21 +## Launch lifecycle
36 -Read these when using this skill:
38 -- `references/protocol.md` — JSON-RPC methods and selector forms.
39 -- `references/workflow.md` — recommended observe/act/wait loop.
40 -- `references/failures.md` — verified broken-flow diagnostics and recovery
41 - examples.
42 -- `references/visual.md` — screenshot, image summary, and diff usage.
43 -- `references/troubleshooting.md` — attach/Wayland/selector/debug notes.
45 -Examples:
47 -- `examples/basic-flow.md`
48 -- `examples/duplicate-review-flow.md`
50 -## Runtime
52 -Use the packaged CLI from this skill directory:
23 +`launch` supervises the app and blocks until it exits. Run it as a long-lived background process, redirect stdout/stderr, and wait for its first JSON line. Do not timeout or kill the launcher while driving the app: its shutdown hook kills the app.
54 25 ```sh
55 -java -jar fxdriver.jar
26 +java -jar fxdriver.jar launch --quiet -- java [options] app.Main > target/fxdriver-launch.json 2> target/fxdriver-launch.err &
58 -fxdriver 0.1.0-SNAPSHOT requires JDK 21+. It is
59 -compiled and tested against JavaFX 21.0.7; target apps provide their
60 -own JavaFX runtime.
29 +Use that JSON file directly for RPC: `java -jar fxdriver.jar rpc target/fxdriver-launch.json capabilities '{}'`; no port/token parsing.
62 -## Rules for agents
31 +## Essential rules
64 -- Prefer stable selectors: `nodeId` / `#id`, `textExact`, `eid`, `role`, then
65 - text contains.
66 -- If important controls have no stable node ids, ask permission to add minimal
67 - semantic JavaFX ids to the app under test. Treat ids as low-risk, persistent
68 - testability improvements: add them only where they make the requested and
69 - likely future navigation meaningfully more stable; follow local naming/style;
70 - keep them in the app unless the human asks otherwise. Never mutate app code
71 - silently.
72 -- Use `value` for `setText`/`type` payloads. `text` is a selector field, not an
73 - input payload.
74 -- `click`/`fire` drive `ButtonBase` controls and `ListView`; use `setValue`,
75 - `selectIndex`, and control-specific methods for choice, picker, range, table,
76 - tree, and tree-table controls. Use `fireMenuItem` for `MenuBar`,
77 - `MenuButton`, `SplitMenuButton`, and context menus. For keyboard-only
78 - interactions (submit with Enter, navigate with Tab/arrows, trigger
79 - accelerators), use `key`.
80 -- Do not rely only on JSON assertions for visual quality. Read screenshots when
81 - layout/colors are under review.
82 -- For whole-flow videos, prefer `canvas:"fixed"` with explicit `width`/`height`,
83 - absolute output paths, and `titleMode:"band"` plus `videoStep` calls before
84 - major phases. Use `quality:"high"` when text/color fidelity matters; keep the
85 - default GIF output when maximum player compatibility matters.
86 -- Do not invent high-level policy checks inside fxdriver. Use primitives
87 - (`snapshot`, `screenshot`, `image-diff`, semantic state) and reason in the
88 - agent/test layer.
89 -- If an action changes UI, follow with `wait`/`assert` and usually a `snapshot`
90 - or `screenshot`.
91 -- Keep artifacts in project-local target/output dirs, not `/tmp`, unless caller
92 - requests otherwise.
33 +- Input payloads use `value`; `text` selects a node.
34 +- `key` emits synthetic JavaFX events, not OS keystrokes.
35 +- `capabilities.workingDirectory` is the app cwd; screenshot paths resolve there.
36 +- `ok:true` means the primitive ran, not that intended state changed—verify afterward.
37 +- Add semantic JavaFX ids only with permission.
38 +- Parse JSON with `jq` or Node, not Python.
39 +- Trust observable UI; do not decompile app/JAR bytecode unless driver evidence cannot answer.
40 +- Video and modal-safe asynchronous dispatch are unavailable.
42 +Read all of `references/protocol.md` in one call only when exact JSON is needed; read `references/troubleshooting.md` only after a failure.

pi/agent/skills/fxdriver/fxdriver.jar

Modified

Previous version contains binary or non-UTF-8 data.

Current version contains binary or non-UTF-8 data.

pi/agent/skills/fxdriver/references/failures.md

Modified
9 9 Observed result:
11 11 ```json
12 -{"result":{"query":"text=Probe buton","present":true,"count":0,"ok":false,"error":{"code":"TIMEOUT","message":"Wait predicate not satisfied"}}}
13 + "result": {
14 + "query": "text=Probe buton",
15 + "present": true,
16 + "count": 0,
17 + "ok": false,
18 + "error": { "code": "TIMEOUT", "message": "Wait predicate not satisfied" }
19 + }
15 23 Useful recovery:
60 68 Observed snapshot fragment:
62 70 ```json
63 -{"type":"Button","id":"","nodeId":"","text":"Tool action","actionable":true}
72 + "type": "Button",
73 + "id": "",
74 + "nodeId": "",
75 + "text": "Tool action",
76 + "actionable": true
66 80 Useful recovery:

pi/agent/skills/fxdriver/references/protocol.md

Modified
8 8 java -jar fxdriver.jar attach <pid> [port]
9 9 java -jar fxdriver.jar launch [port] -- \
10 10 java [java-options...] <main-or-jar> [args...]
11 -java -jar fxdriver.jar rpc <port> <method> '<params-json>' [token]
11 +java -jar fxdriver.jar rpc <port|launch-json> <method> '<params-json>' [token]
12 12 java -jar fxdriver.jar snapshot <port> [--summary] [token]
16 16 first fxdriver-owned CLI output line is machine-readable JSON with `pid`,
17 17 `port`, `token`, `endpoint`, and `endpointFile`. Compatibility lines still print
18 18 the chosen port, an endpoint file, and `FXDRIVER_TOKEN`. RPC calls require that
19 -token via `FXDRIVER_TOKEN` or the optional final token argument.
19 +token via `FXDRIVER_TOKEN` or the optional final token argument. `rpc` also accepts a saved launch JSON file and reads its port/token directly.
21 21 ## Attach vs launch
39 39 Current launch mode injects `-javaagent` after `java` and supports direct Java
40 -commands only.
40 +commands only. It supervises the child and blocks until the app exits. Run it
41 +as a persistent/background process, capture its first JSON stdout line, and keep
42 +the launcher alive: killing it also kills the app.
42 44 Example launch JSON:
69 71 java -jar fxdriver.jar rpc <port> capabilities '{}'
72 -Use these before relying on optional methods or selector forms.
74 +Use these before relying on optional methods or selector forms. `capabilities` also returns `workingDirectory`, the base for relative screenshot paths.
74 76 ### `configure`
92 94 `highlightMs:0` disables trace for that action.
96 +### `run`, batch, and `mark`
98 +Group dependent actions with `run`; each step uses `op` (or `method`) plus the
99 +normal method parameters. It stops on the first failed step unless
100 +`continueOnError:true`. `returnState:"compact"` adds bounded state.
102 +```sh
103 +java -jar fxdriver.jar rpc <port> run '{"steps":[{"op":"setText","nodeId":"name","value":"Ada"},{"op":"wait","textExact":"Ada"}],"returnState":"compact"}'
104 +java -jar fxdriver.jar rpc <port> mark '{}'
105 +```
107 +The HTTP endpoint also accepts a raw JSON-RPC request array as a batch. `mark`
108 +visually marks showing stages and needs no parameters.
94 110 ### `snapshot`
171 187 java -jar fxdriver.jar snapshot <port> --summary
174 -The CLI summary command returns a compact first view:
190 +The CLI summary command returns a compact first view. It caps windows at 8,
191 +buttons at 24, text fields at 16, value controls at 24, menus at 16, tables at
192 +12, selected tabs at 12, and the distinct visible-text sample at 40 strings. Integration tests enforce a 16 KiB
193 +response bound for the focused fixture.
176 -- `windows[]`: window id/index/title/focus/bounds.
177 -- `buttons[]`: visible `ButtonBase` controls with text.
195 +- `windows[]`: window id/title/focus/bounds.
196 +- `buttons[]`: visible `ButtonBase` controls with text and disabled state.
178 197 - `textFields[]`: text inputs with value/prompt/editability.
198 +- `controls[]`: toggles and choice/date/spinner/range values.
199 +- `menus[]`: menu controls and context-menu targets with nested item paths.
179 200 - `tables[]`: visible `TableView` and `TreeTableView` row/column summaries.
180 201 - `selectedTabs[]`: selected tab text per visible `TabPane`.
181 -- `visibleTextSample[]`: bounded visible text sample for orientation.
202 +- `focusedNode`: target metadata or `null`.
203 +- `visibleTextSample[]`: bounded visible text for orientation.
183 -Use full `snapshot` when you need bounds, semantics, or raw node hierarchy.
205 +Use full `snapshot` when you need complete semantics or raw node hierarchy.
185 207 ### `highlight`
238 260 java -jar fxdriver.jar rpc <port> key '{"nodeId":"search","chars":"hello"}'
241 -Sends real keystrokes as synthetic `KEY_PRESSED`/`KEY_TYPED`/`KEY_RELEASED`
242 -events (works headless, unlike OS-level robot keys). `key` is a single named key
243 -or chord — `ENTER`, `ESCAPE`/`ESC`, `TAB`, `UP`/`DOWN`/`LEFT`/`RIGHT`,
244 -`F1`–`F12`, letters, `CTRL+S`, `SHIFT+TAB`, `ALT+`/`META+`/`CMD+`. `chars` types
245 -a literal string. With a selector (`nodeId`, `textExact`, …) the target node is
246 -focused first; otherwise events go to the current focus owner. Returns the
247 -resolved key/chars and a description of the target node.
263 +Dispatches synthetic JavaFX `KeyEvent`s to a node; it is not OS/global input.
264 +`key` accepts one named key or chord such as `ENTER`, `ESCAPE`/`ESC`, `TAB`,
265 +`F1`, `CTRL+S`, `SHIFT+TAB`, or `META+K`. `chars` emits one `KEY_TYPED` event
266 +per Unicode code point. With a selector (`nodeId`, `textExact`, …), the first
267 +match is focused; otherwise the current JavaFX focus owner is used. The result
268 +contains `key`, `chars`, `sent`, and `target`; no target returns `NO_FOCUS`.
249 270 ### `setValue`, `selectIndex`, `selectListItem`
258 279 controls with a direct value such as `ChoiceBox`, `ComboBox`, `DatePicker`,
259 280 `Slider`, and text-like value controls. Use `selectIndex` for indexed selection
260 281 in list/table/tree-style controls. Use `selectListItem` for `ListView` by item
261 -text.
282 +text. A generic `select` method is intentionally unsupported.
284 +### Choice, popup, and step controls
286 +```sh
287 +java -jar fxdriver.jar rpc <port> setValue '{"nodeId":"theme","value":"Dark"}'
288 +java -jar fxdriver.jar rpc <port> showPopup '{"nodeId":"density"}'
289 +java -jar fxdriver.jar rpc <port> hidePopup '{"nodeId":"density"}'
290 +java -jar fxdriver.jar rpc <port> increment '{"nodeId":"days","steps":5}'
291 +java -jar fxdriver.jar rpc <port> decrement '{"nodeId":"days","steps":2}'
292 +```
294 +`setValue` supports choice/combo/date/range/spinner controls. Increment and
295 +decrement default to one step.
263 297 ### `tableCell`
267 301 java -jar fxdriver.jar rpc <port> tableCell '{"nodeId":"projects","rowIndex":2,"columnIndex":0}'
270 -Returns a `TableView` or `TreeTableView` cell by row text/row index and
271 -column text, id, or index. The result includes `rowIndex`, `columnIndex`,
272 -resolved `column`, full `rowText`, `value`, and `ok`.
304 +Reads `TableView` or `TreeTableView` model values by row text/row index and
305 +flat top-level column text, id, or index. It does not depend on realized cell
306 +nodes. The result includes `rowIndex`, `columnIndex`, resolved `column`, full
307 +`rowText`, `value`, and `ok`; failures use `NO_TABLE`, `NO_ROW`, or `NO_COLUMN`.
274 309 ### `fireMenuItem`
281 316 Fires `MenuBar`, `MenuButton`, `SplitMenuButton`, or context-menu items without
282 -showing the popup. Use `path` for nested menu traversal or `itemText` to find
283 -the first matching item recursively. Returns the menu kind, resolved value, and
284 -`fired`.
317 +showing a JavaFX popup. It cannot operate native menus or dialogs. Use `path`
318 +for nested traversal or `itemText` for exact-then-contains recursive lookup.
319 +The result contains `query`, `kind`, `path`, `value`, and `fired`; failures use
320 +`NO_MENU_ITEM` or `DISABLED`.
286 322 ### `wait`
295 331 `enabled`, `focused`, `visible`. Like the action commands, `wait` and `assert`
296 332 only consider visible nodes unless `visible:false` is passed explicitly, so a
297 333 satisfied `wait` means the follow-up `click`/`type` sees the same node. Failed
298 -waits return `ok:false` with `TIMEOUT`; take a fresh snapshot or CLI summary to
299 -compare visible text, ids, roles, and control state before retrying.
334 +waits return `ok:false` with `TIMEOUT` and up to five bounded `nearMatches`.
335 +Each candidate has `eid`, `type`, `id`, `text`, and diagnostic `selectorPath`.
336 +Near matches and selector paths explain misses; they are not supported
337 +selectors. Successful waits omit `nearMatches`.
301 339 ### `assert`
309 347 error (top-level `error` member); app-level `ok:false` results exit zero and
310 348 need inspection in scripts.
312 -### `events`, `clearEvents`
350 +### `events`, `eventsSince`, `clearEvents`
315 353 java -jar fxdriver.jar rpc <port> events '{}'
354 +java -jar fxdriver.jar rpc <port> eventsSince '{"cursor":20}'
355 +java -jar fxdriver.jar rpc <port> eventsSince '{"since":1735689600000}'
316 356 java -jar fxdriver.jar rpc <port> events '{"clear":true}'
317 357 java -jar fxdriver.jar rpc <port> clearEvents '{}'
320 360 Returns recent fxdriver calls with `ts`, `method`, `ok`, and `params`. If
321 361 request params include `tag` or `scenario`, the event copies them to top-level
322 -fields. Use `events {"clear":true}` to read and clear in one call.
362 +fields. `eventsSince` accepts an event cursor or millisecond timestamp. Use `events {"clear":true}` to read and clear in one call.
324 364 ### `screenshot`
326 -CLI shortcut for first visible stage/window:
366 +CLI shortcut for the focused showing stage, then first showing stage:
329 369 java -jar fxdriver.jar screenshot <port> target/fxdriver.png
341 381 A relative `path` resolves against the target app's working directory, not the
342 382 caller's — pass an absolute path (or use the CLI `screenshot` subcommand, which
343 383 absolutizes before sending). The result echoes the absolute path written. Window
344 -and rect targets default to the first showing stage; pass `window` with a `wid`
345 -from snapshot (`"w2"`) to capture another stage. `press` accepts the same
346 -`window` parameter to scope accelerators.
384 +and rect targets default to the focused showing JavaFX stage, then the first
385 +showing stage; pass `window` with a stage `wid` from snapshot (`"w2"`) to
386 +capture that exact stage. Popup window ids are rejected. `press` accepts the
387 +same parameter to scope accelerators.
348 389 Captures optimized lossless PNG. RPC results include `path`, `bytes`, `target`,
349 -`image` bounds, `source` bounds/units, `scale`, `activeWindow`, and
350 -`visibleTextSample`. CLI screenshot prints that result plus image summary.
351 -Opaque screenshots may be encoded as RGB; transparent screenshots preserve
352 -alpha.
390 +`image` bounds, `source` bounds/units, `scale`, `activeWindow`, and a bounded
391 +`visibleTextSample` for orientation. `activeWindow` contains only id, title,
392 +bounds, and focused-node metadata—not a recursive snapshot. CLI screenshot
393 +prints that result plus image summary. Opaque screenshots may be encoded as
394 +RGB; transparent screenshots preserve alpha.
354 -### `videoStart`, `videoStep`, `videoStop`
396 +### Video and modal dispatch
356 -```sh
357 -java -jar fxdriver.jar rpc <port> videoStart '{"path":"/tmp/run/run.gif","fps":10,"canvas":"fixed","width":1280,"height":900,"titleMode":"band"}'
358 -java -jar fxdriver.jar rpc <port> videoStep '{"title":"Login"}'
359 -java -jar fxdriver.jar rpc <port> videoStop '{}'
360 -```
362 -Records one stage's scene into GIF by default or APNG with `quality:"high"`.
363 -Frames are captured on a timer and encoded as delta rects on a background
364 -thread: unchanged ticks cost no bytes, and the UI thread is never blocked on
365 -encoding (frames are dropped instead and reported as `dropped`; frame delays
366 -come from capture timestamps, so playback speed stays true to wall clock even
367 -under load). Params: `path` (resolved in the target JVM's working directory —
368 -prefer absolute), `fps` (default 10, clamped to 1-30), `maxMs` (hard cap,
369 -default 120000, clamped to 1000-3600000), `quality` (`low` GIF or `high` APNG),
370 -`window` (a `wid` from snapshot), `scalePercent` (clamped to 25-200, default
371 -100), `canvas`, `width`, `height`, `background`, `titleMode`, `titleHeight`,
372 -and `title`. One recording at a time: a second `videoStart` while recording
373 -returns an error.
375 -Canvas modes:
377 -- `canvas:"fixed"` uses explicit `width` and `height`; use this for
378 - deterministic test videos.
379 -- `canvas:"screen"` (default) uses a stable primary-screen canvas so
380 - login/splash windows do not trap the recording at their small size.
381 -- `canvas:"firstFrame"` preserves the older behavior where the first captured
382 - frame defines the animation canvas; use only for small, single-window
383 - captures or scalePercent comparisons.
385 -Every source frame is composed into the stable canvas. Oversized source frames
386 -are scaled down to fit and centered; smaller windows are centered on the
387 -`background` color (`#RRGGBB` or `#AARRGGBB`, default white).
389 -Native step titles are recorder overlays, not app UI. Set `titleMode:"band"` to
390 -reserve a title bar inside the video canvas, or `titleMode:"overlay"` for a
391 -translucent top-left label. `title` sets the initial title;
392 -`videoStep {"title":"..."}` changes it during recording and forces an immediate
393 -capture tick. `titleMode:"off"` disables drawing titles.
395 -`videoStop` returns `path`, `frames` (encoded), `captured`, `dropped`,
396 -`durationMs`, `bytes`, `startedAt` (epoch ms — correlate with `events`
397 -timestamps to map actions to video time), `canvasWidth`, `canvasHeight`,
398 -`canvas`, `titleMode`, `quality`, `format`, `steps`, `scaledFrames`, and `ok`.
399 -`ok:false` carries an error code: `NO_VIDEO` (nothing to stop), `NO_FRAMES` (no
400 -showing stage ever matched, no file written), `VIDEO_FAILED` (encoder error,
401 -e.g. unwritable path), or `VIDEO_STALLED`. Recording also finalizes on
402 -`shutdown` and on JVM exit. GIF is streamed, so even a killed process can leave
403 -the file playable through the last flushed frame. APNG is patched on close and
404 -requires normal finalization to be playable.
398 +`videoStart`, `videoStep`, and `videoStop` are not available in this phase.
399 +Modal-safe asynchronous action dispatch is also deferred. Check `capabilities`
400 +rather than assuming either API exists.
406 402 ### `image-summary`
451 447 java -jar fxdriver.jar rpc <port> shutdown '{}'
454 -Stops the target JVM's fxdriver RPC server, not the app itself.
450 +Stops the RPC server. Apps started by `launch` exit; attached apps keep running. `exitApp:true` explicitly exits either.
456 452 ## Selectors
486 482 { "accessible": "Save" }
487 483 { "selector": "type=Button" }
486 +Snapshot and near-match `selectorPath` values are diagnostics only and cannot
487 +be passed back as selectors. Generic `select` is unsupported; use the explicit
488 +selection methods above.

pi/agent/skills/fxdriver/references/workflow.md

Modified
52 52 5. `type` for broad discovery only
53 53 6. bare text contains only as last resort
55 +Do not copy snapshot or near-match `selectorPath` diagnostics into requests.
56 +They are deliberately not selectors.
55 58 Verify ambiguous selectors with `highlight`:
57 60 ```sh
74 77 java -jar fxdriver.jar rpc <port> click '{"textExact":"Projects","untilQuietMs":500,"timeoutMs":10000}'
75 78 java -jar fxdriver.jar rpc <port> setText '{"nodeId":"filter-duplicates","value":"portrait"}'
76 79 java -jar fxdriver.jar rpc <port> selectListItem '{"nodeId":"duplicates-list","itemText":"portrait"}'
80 +java -jar fxdriver.jar rpc <port> key '{"nodeId":"filter-duplicates","key":"ENTER"}'
81 +java -jar fxdriver.jar rpc <port> fireMenuItem '{"nodeId":"main-menu","path":["File","Save"]}'
77 82 java -jar fxdriver.jar rpc <port> tableCell '{"nodeId":"projects","tableText":"MDP_40982497","column":"Projektnummer"}'
85 +`key` is synthetic JavaFX input, not OS/global input. Menu firing resolves and
86 +fires the model item without showing its JavaFX popup. `tableCell` reads model
87 +values from flat columns. There is no generic `select`; choose the explicit
88 +selection method for the control.
80 90 ## Wait/assert
82 92 After action, wait for observable state:
89 99 Do not assume immediate UI update after action.
91 -If a wait fails, read the returned `ok:false`/`TIMEOUT`, then take a fresh
92 -summary or full snapshot and compare visible text, ids, roles, and control
93 -state before trying another selector.
101 +If a wait fails, read the returned `ok:false`/`TIMEOUT` and its at-most-five
102 +`nearMatches`, then take a fresh summary or full snapshot if needed. Near-match
103 +ids/text/types help diagnose a typo; their selector paths are not selectors.
95 105 ## Visual review
104 114 java -jar fxdriver.jar image-diff target/before.png target/after.png target/diff.png
107 -Read screenshots. Diff alone tells change amount, not quality.
117 +Read screenshots. Diff alone tells change amount, not quality. Screenshot JSON
118 +also identifies `activeWindow` and provides a bounded `visibleTextSample` for
119 +orientation; it is not a replacement for reading the image.
109 121 ## Video evidence
111 -For real app flows, prefer a fixed video canvas and native step titles:
113 -```sh
114 -java -jar fxdriver.jar rpc <port> videoStart '{"path":"/abs/run/flow.gif","canvas":"fixed","width":1280,"height":900,"titleMode":"band","title":"Login"}'
115 -java -jar fxdriver.jar rpc <port> videoStep '{"title":"Create project"}'
116 -# act/wait/assert
117 -java -jar fxdriver.jar rpc <port> videoStep '{"title":"Search results"}'
118 -java -jar fxdriver.jar rpc <port> videoStop '{}'
119 -```
121 -Use `canvas:"fixed"` whenever the flow may switch between login, splash, main,
122 -or modal windows. Use absolute paths so artifacts land where the caller expects.
123 -Check `videoStop` for `canvasWidth`, `canvasHeight`, `steps`, and
124 -`scaledFrames`; do not assume a GIF is readable merely because it exists.
123 +Video RPCs are not available in this phase. Check `capabilities`; use repeated
124 +screenshots when still-image evidence is sufficient. Modal-safe asynchronous
125 +action dispatch is also outside this phase.
126 127 ## Failure artifacts

pi/agent/skills/isp-start-day/SKILL.md

Modified
2 2 name: isp-start-day
3 -description: Daily ISP-INsoft start-of-day compliance check. Use when starting workday, validating Bürobelegung, Jira sprint state, KKG PRs, and local KKG branches/worktrees. Skips Tempo. Gives terse setup help when deps/auth are missing. Cross-platform Node implementation; no Bash. Never mutates Jira, Confluence, GitHub, or git state without explicit confirmation.
3 +description: Daily ISP-Insoft start-of-day compliance check. Use when starting workday, validating Bürobelegung, Jira sprint state, KKG PRs, and local KKG branches/worktrees. Skips Tempo. Gives terse setup help when deps/auth are missing. Cross-platform Node implementation; no Bash. Never mutates Jira, Confluence, GitHub, or git state without explicit confirmation.
6 6 # isp-start-day
8 -Daily start-of-day workflow for ISP-INsoft process hygiene.
8 +Daily start-of-day workflow for ISP-Insoft process hygiene.
10 10 ## Contract

zed/settings.json

Modified

Previous version contains binary or non-UTF-8 data.

Current version contains binary or non-UTF-8 data.