I tend to think of puzzles as skill challenges tbh. Here is a problem, when they ask questions that lead to using a skill they roll, if they succeed, they get information that lets them solve the puzzle (maybe there’s like one dot to connect but it’s not meant to be difficult). If they fail, either fall back on another skill (nature didn’t work, what if we use science as a different approach) or have them fail forward: they get the info they needed but something bad happens

This was a puzzle dungeon gym challenge I ran that the players still think was one of the top gym challenges

Note, most of them can be approached brute force with a high DC Athletics. That’s in essence a failback if they don’t ask questions and try to use their other skills to create solutions

Also note, these are not the only solutions. I like to write out a few solutions to test the viability of the puzzle. If I can’t come up three ways to approach the problem, it’s probably too abstract in it’s current state. If the PC comes to me with a different idea from what I have written down, I’ll just run with that

Writing the solutions also helps me add more detail to the description, for example if I want to give Ponyta the chance to use it’s Agility to make the challenge easier, I’ll know I have to add a way for that to make the puzzle easier
(the valve she can turn on the other side)

Oh and third note this should be a blog post: Skill Challenges are good, but the most trainer game thing you can do is have challenges that are completely circumvented by a party member’s pokemon using a move. The agility is one example of that, setting up a move as the solution to the puzzle is basically making an HM out of any move you want